=== relaybell Web Push ===
Contributors: relaybell
Tags: push notifications, web push, woocommerce, notifications, marketing
Requires at least: 5.6
Tested up to: 6.6
Requires PHP: 7.2
Stable tag: 1.1.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Web push notifications for WordPress & WooCommerce. Collect subscribers, auto-push new posts, and fire commerce events (purchase, cart, back-in-stock, price-drop).

== Description ==

relaybell adds browser push notifications to any WordPress site. Visitors opt in
with a native prompt, and you reach them again with a click — no app, no email
address required.

**Core**

* Opt-in prompt powered by the relaybell browser SDK.
* Automatic push when you publish — choose which post types, attach the featured
  image, and optionally route posts to a topic that matches the primary
  category slug.
* Root-scoped service worker served straight from WordPress.
* Identify logged-in users by account email so behavioral and cross-device
  targeting work (filterable to a hashed id).

**WooCommerce**

When WooCommerce is active, relaybell automatically fires behavioral events to
your relaybell project — no code, just save an API key. Each event can be toggled
on or off under **Settings → relaybell**:

* `purchase` — order paid or completed (de-duplicated per order).
* `cart.updated` — item added to cart.
* `back_in_stock` — a product returns to stock (quantity- or status-managed).
* `price_drop` — a product's effective price falls below its last baseline.
* `signup` — a new customer / user registers.
* `checkout.started` — an order is created at checkout.
* `order.refunded` — an order is refunded.

It also adds an optional **"Notify me when back in stock"** button on
out-of-stock product pages that subscribes the shopper and tags their interest.

HPOS (High-Performance Order Storage / custom order tables) is fully supported.

== Installation ==

1. Upload the `relaybell` folder to `/wp-content/plugins/`, or install the ZIP
   from **Plugins → Add New → Upload Plugin**.
2. Activate **relaybell Web Push**.
3. Go to **Settings → relaybell** and enter your **Project ID** and **API key**
   (from your relaybell dashboard → Settings → API keys).
4. Optionally enable **Send on publish** and pick which post types push.

The WooCommerce bridge auto-loads when WooCommerce is active — there is nothing
extra to include. Just make sure an API key is saved.

== External services ==

This plugin connects to **relaybell** (https://relaybell.com), a web push
notification service operated by Nexistech. relaybell is required for the plugin
to function: browser push notifications cannot be stored or delivered without a
push service, and this plugin is the WordPress client for that service. You need
a relaybell account and API key to use the plugin.

**1. The relaybell browser SDK (https://relaybell.com/relaybell-sdk.js)**

The SDK script is loaded on your site's front end so visitors can opt in to push
notifications. This happens on page load, for every visitor, once you have saved
a Project ID. The visitor's browser sends its normal request data to relaybell
(IP address and user agent) when it loads the script.

**2. Subscribing a visitor (POST https://relaybell.com/api/v1/subscribers)**

When a visitor accepts the browser's notification prompt, the SDK sends their
push subscription to relaybell: the browser-issued push endpoint URL and its
encryption keys, plus the page URL, and any topic or tags you have configured.
If the visitor is logged in to WordPress, their account email is also sent as an
`externalId` so you can target them across devices — you can replace this with a
hashed value using the `relaybell_external_id` filter, or remove it entirely.
This is only sent for logged-in users, and only after the visitor has opted in
to notifications.

**3. Sending notifications (POST https://relaybell.com/api/v1/notifications)**

When you publish a post (if "Send on publish" is enabled), the post title,
excerpt, permalink and featured image URL are sent to relaybell so it can build
the notification. Your API key authenticates the request.

**4. WooCommerce events (POST https://relaybell.com/api/v1/events)**

If WooCommerce is active, the plugin sends commerce event data — for example an
order's id, total, currency and product ids on `purchase`, or a product id and
price on `price_drop`. These are sent at the moment the event happens on your
store. These events are **enabled by default** once WooCommerce is active and an
API key is saved; each one can be turned off individually under **Settings →
relaybell**.

**5. Admin actions (GET/POST https://relaybell.com/api/v1/...)**

"Test connection" and "Send test push" on the settings screen, and the live
subscriber count shown there, call relaybell from your admin with your API key.
These only run in wp-admin.

No data is sent anywhere until you save a Project ID and API key.

Service provider: Nexistech (https://nexistech.in)
Terms of service: https://relaybell.com/terms
Privacy policy: https://relaybell.com/privacy
Data processing agreement: https://relaybell.com/dpa

== Frequently Asked Questions ==

= Do I need WooCommerce? =

No. Without WooCommerce you still get the opt-in prompt and publish-time pushes.
The commerce events simply activate when WooCommerce is present.

= Do subscribers need to give an email address? =

No. Web push works from the browser subscription alone. If a user is logged in,
relaybell also binds their account email as an `externalId` for richer targeting;
you can substitute a hashed value with the `relaybell_external_id` filter.

= How do I send a test notification? =

On **Settings → relaybell**, use **Test connection** to verify your key and see
your subscriber count, or **Send test push** to broadcast a test to your current
subscribers.

= Does it support HPOS (custom order tables)? =

Yes. The plugin declares `custom_order_tables` compatibility and uses the
WooCommerce CRUD APIs throughout.

= Which hooks/filters can I use? =

* `relaybell_external_id` — swap the account email for a hashed id.
* `relaybell_sdk_init` — modify the full SDK init options.
* `relaybell_publish_payload` — modify the publish push body.
* `relaybell_category_topic` — map a post's primary category to a topic id.
* `relaybell_woo_event_payload` — modify any commerce event body before sending.

== Changelog ==

= 1.1.1 =
* Change: the browser SDK is now registered with `wp_enqueue_script()` and
  `wp_add_inline_script()` instead of being printed directly into the footer, so
  it respects script dependencies, versioning, and other plugins' filters.
* Docs: documented every relaybell endpoint the plugin contacts, and what is
  sent to each, under "External services".

= 1.1.0 =
* New: `price_drop`, `signup`, `checkout.started`, and `order.refunded`
  WooCommerce events.
* New: back-in-stock now also fires for status-only stock toggles (no managed
  quantity), guarded against double-firing.
* New: "Notify me when back in stock" waitlist button on out-of-stock products.
* New: identify logged-in users by email (with `relaybell_external_id` filter)
  and pass their role as a tag.
* New: richer publish push — featured image, selectable post types, optional
  category→topic routing, and a `relaybell_publish_payload` filter.
* New: redesigned settings screen with General / Post types / WooCommerce
  sections, per-event toggles, sanitized settings, a Settings shortcut link,
  a missing-key admin notice, a live subscriber count, and Test connection /
  Send test push buttons.
* New: HPOS (custom order tables) compatibility declaration.
* New: `uninstall.php` cleans up all options and meta on delete.
* i18n: user-facing strings are now translatable (text domain `relaybell`).

= 1.0.0 =
* Initial release: opt-in prompt, publish-time push, service worker, and the
  WooCommerce `purchase` / `cart.updated` / `back_in_stock` events.

== Upgrade Notice ==

= 1.1.1 =
Internal change to how the browser SDK is loaded, plus a full disclosure of the
relaybell endpoints the plugin contacts. No settings changes needed.

= 1.1.0 =
Adds price-drop, signup, checkout, and refund events, a waitlist button, a
redesigned settings screen, and HPOS support. Review the new per-event toggles
under Settings → relaybell after updating.
