# Contract

Hooks this plugin emits (`do_action`) or consumes (`apply_filters`) that
cross a repository boundary. Internal wiring (`add_action` / `add_filter`
on `nlrem_*`) is not a contract and is not listed here.

## Emitted by this plugin

These `do_action` calls are the plugin's outward signal. A sibling plugin
or a site developer can subscribe to any of them with `add_action`.

| Hook | Args | Fired when |
|------|------|------------|
| `nlrem_cart_abandoned` | `$cart_id` (int) | A cart crosses the abandon threshold and is marked `abandoned`. |
| `nlrem_cart_resumed` | `$cart_id` (int) | A customer revisits an abandoned cart before purchase. |
| `nlrem_cart_completed` | `$cart_id` (int) | An order for the cart reaches `completed` status. |
| `nlrem_cart_expired` | `$cart_id` (int) | The retention sweep expires a cart record. |
| `nlrem_abandon_sweep_complete` | `$marked` (int, count) | The hourly abandon sweep finishes. |
| `nlrem_send_sweep_complete` | `$sent` (int, count) | The hourly send sweep finishes. |
| `nlrem_retention_complete` | `$cutoff` (string, datetime) | The daily retention sweep finishes. |
| `nlrem_email_sent` | `$cart_id` (int), `$step` (int), `$email` (string) | A reminder email dispatches successfully. |
| `nlrem_email_failed` | `$cart_id` (int), `$step` (int), `$email` (string), `$sent` (WP_Error or false) | `wp_mail()` returns a failure for a reminder email. |
| `nlrem_unsubscribed` | `$cart_id` (int), `$email` (string) | A customer clicks the unsubscribe link. |

## Consumed by this plugin

This plugin calls `apply_filters` on the following family hooks. A sibling
plugin (or site code) can alter the behaviour by adding a filter.

| Hook | Default | Where | Effect of filtering |
|------|---------|-------|---------------------|
| `wpmgr_menu_title` | `'Manager'` | `includes/shared-menu.php` | Changes the parent menu label in the wp-admin sidebar. |
| `wpmgr_menu_glyph` | `'∞'` | `includes/shared-menu.php` | Changes the sidebar glyph for the Nolimit menu group. |
| `wpmgr_dashboard_cards` | `array()` | `includes/shared-menu.php` | Supplies the dashboard summary cards shown on the family landing page. This plugin contributes one card via `add_filter`. |

## Internal cron hooks

The following are WordPress cron event names registered by this plugin.
They are **not** a contract: no sibling plugin should subscribe to them,
and they will not appear in the tables above. They exist so that an
administrator can see the schedule in a cron plugin and so that
`wp_clear_scheduled_hook()` can target them on deactivation.

| Cron hook | Schedule |
|-----------|----------|
| `nlrem_sweep_abandoned` | `nlrem_five_minutes` |
| `nlrem_sweep_send` | `nlrem_five_minutes` |
| `nlrem_cleanup_retention` | `daily` |

## Notes

- The `wpmgr_dashboard_cards` filter is answered by this plugin via
  `add_filter( 'wpmgr_dashboard_cards', ... )` in
  `includes/shared-menu.php`. The returned array element carries the
  plugin's summary counts (tracked carts, abandoned, emails sent,
  unsubscribe rate).
- No REST routes are registered. The only front-end surface is the
  unsubscribe query argument `?nlrem_unsub={token}`, which is handled on
  `template_redirect`.
- No options are exposed as a filter. Settings are read via
  `NLREM_Settings::get()` and written via the admin form. A sibling that
  needs to override a default should use `add_filter` on
  `pre_option_nlrem_settings` (the standard WordPress options filter).