Release 1.1.0

.distignore

@@ -39,6 +39,8 @@ eslint.config.cjs
 mise.toml
 phpunit.xml
 phpunit.xml.dist
+playwright.config.js
+.env.build.example
 README.md
 docker-compose.extra-hosts.example.yml
 docker-compose.extra-hosts.yml

.env.build.example

@@ -0,0 +1,4 @@
+# Copy to .env.build (gitignored) for `npm run build:zip:release`.
+# Mirrors the BEEHIIV_REGISTRATION_TOKEN GitHub Actions secret used in
+# .github/workflows/deploy.yml to produce a zip matching the .org release.
+BEEHIIV_REGISTRATION_TOKEN=

.github/workflows/test.yml

@@ -0,0 +1,138 @@
+name: Test
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+
+concurrency:
+  group: test-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit-tests:
+    name: "PHPUnit (PHP ${{ matrix.php-version }}, WP ${{ matrix.wp-version }})"
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # Keep in sync with "Requires PHP" / "Requires at least" in readme.txt.
+        php-version: ["7.4", "8.0", "8.1", "8.2", "8.3"]
+        wp-version: ["6.8", "latest"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          tools: composer:v2
+          coverage: none
+
+      - name: Install Composer dependencies
+        run: composer install --prefer-dist --no-progress
+
+      - name: Install npm dependencies
+        run: npm ci
+
+      - name: Pin wp-env PHP/WP core version
+        run: npm run env:set-version -- --php=${{ matrix.php-version }} --wp=${{ matrix.wp-version }}
+
+      - name: Patch archived Debian base image (PHP 7.4 / 8.0)
+        if: matrix.php-version == '7.4' || matrix.php-version == '8.0'
+        run: scripts/ci-patch-debian-base.sh ${{ matrix.php-version }}
+
+      - name: Start wp-env
+        run: npx wp-env start
+
+      - name: Run PHPUnit
+        run: npx wp-env run tests-cli -- bash -c "cd wp-content/plugins/$(basename "$GITHUB_WORKSPACE") && composer test"
+
+      - name: Generate PHPUnit dashboard
+        if: always()
+        run: node tests/phpunit/report/generate-dashboard.js --label="PHP ${{ matrix.php-version }} / WP ${{ matrix.wp-version }}"
+
+      - name: Upload PHPUnit dashboard
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: phpunit-report-php${{ matrix.php-version }}-wp${{ matrix.wp-version }}
+          path: tests/phpunit/test-results
+          retention-days: 7
+
+      - name: Stop wp-env
+        if: always()
+        run: npx wp-env stop
+
+  e2e:
+    name: E2E tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "7.4"
+          tools: composer:v2
+          coverage: none
+
+      - name: Install Composer dependencies
+        run: composer install --prefer-dist --no-progress
+
+      - name: Install npm dependencies
+        run: npm ci
+
+      - name: Build plugin assets
+        run: npm run build
+
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Patch archived Debian base image (PHP 7.4)
+        run: scripts/ci-patch-debian-base.sh 7.4
+
+      - name: Start wp-env
+        run: npx wp-env start
+
+      - name: Run Playwright E2E tests
+        run: npx playwright test
+
+      - name: Upload Playwright report on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: tests/e2e/test-results
+          retention-days: 7
+
+      - name: Stop wp-env
+        if: always()
+        run: npx wp-env stop

.gitignore

@@ -13,10 +13,12 @@ coverage
 tests/php-coverage
 .phpunit.result.cache
 tests/e2e/test-results
+tests/phpunit/test-results
 
 # Directories/files that may appear in your environment
 .wp-env.override.json
 docker-compose.extra-hosts.yml
+.env.build
 .DS_Store
 Thumbs.db
 wp-cli.local.yml

.wp-env.json

@@ -5,7 +5,17 @@
 	"themes": [ "https://downloads.wordpress.org/theme/twentytwentyfive.zip" ],
 	"config": {
 		"WP_DEBUG": true,
-		"SCRIPT_DEBUG": true
+		"SCRIPT_DEBUG": true,
+		"AUTOMATIC_UPDATER_DISABLED": true
 	},
-	"testsEnvironment": false
+	"port": 8890,
+	"testsEnvironment": true,
+	"env": {
+		"tests": {
+			"port": 8891,
+			"mappings": {
+				"wp-content/mu-plugins": "./tests/e2e/plugins"
+			}
+		}
+	}
 }

README.md

@@ -68,6 +68,22 @@ Without Doppler, define the same constants in `wp-config.php`, or put them in a
 
 If your local app uses HTTPS with a private CA, set `BEEHIIV_SSLVERIFY` to `false` (or install that CA in the WordPress container). PHP’s cURL does not trust host mkcert/Caddy CAs by default.
 
+### Backward-compatibility testing (wp-env)
+
+Point wp-env at a specific PHP / WordPress core version to check compatibility with older or newer combinations than your default local setup, and get an HTML dashboard for that combination:
+
+```bash
+npm run test:compat -- --php=8.1 --wp=6.8
+```
+
+That pins wp-env to PHP 8.1 / WP 6.8 (leaving it set for subsequent `npm run env:start` runs — clear with `npm run env:set-version -- --clear`), **destroys and recreates the wp-env environment** so the combination starts from a genuinely clean install, runs PHPUnit, and writes `tests/phpunit/test-results/php8.1-wp6.8/dashboard.html` — pass/fail counts, a per-class breakdown, and failure details. Run it again with different `--php`/`--wp` values to get a separate dashboard per combination; nothing gets overwritten. `--wp` accepts a WordPress.org release number (e.g. `6.8`), `latest` (wp-env's own default), or `nightly`.
+
+⚠️ `test:compat` deletes your current wp-env database and content for this project (`wp-env destroy`) every time it runs. Only use it against a wp-env instance you're fine wiping — not one with dev content you want to keep.
+
+To only change the pinned version without wiping anything, use `npm run env:set-version -- --php=8.1 --wp=6.8` directly — it writes to the gitignored `.wp-env.override.json`, so it never touches tracked config, and wp-env rebuilds the WordPress core files (not the database) the next time it starts. Because the database is left as-is, wp-admin will show the "database needs to be updated" screen after switching to a different WP version; run `npm run env:destroy` first if you want a clean database for manual browsing too. `npm run test:php:report` regenerates a dashboard from an existing JUnit report (e.g. after `composer test`) without re-running anything.
+
+CI runs the full PHP × WP matrix on every PR (see `.github/workflows/test.yml`) and uploads one `phpunit-report-php{X}-wp{Y}` dashboard artifact per combination.
+
 ## Development Commands
 
 | Command                     | Purpose                                              |
@@ -77,8 +93,11 @@ If your local app uses HTTPS with a private CA, set `BEEHIIV_SSLVERIFY` to `fals
 | `npm run env:start`         | Start wp-env (+ optional extra_hosts overlay)        |
 | `npm run env:start:doppler` | Start with Doppler-mounted OAuth/API overrides       |
 | `npm run env:hosts`         | Re-apply `docker-compose.extra-hosts.yml` if present |
+| `npm run env:set-version`   | Pin wp-env's PHP/WP core version (`--php` / `--wp`)  |
 | `npm run env:stop`          | Stop wp-env                                          |
 | `npm run env:destroy`       | Tear down wp-env                                     |
+| `npm run test:compat`       | Run PHPUnit for one PHP/WP combo + its own dashboard |
+| `npm run test:php:report`   | Regenerate a PHPUnit dashboard from an existing run  |
 | `npm run lint`              | Lint JS, CSS, and PHP (or individually)              |
 
 ## Project layout

beehiiv.php

@@ -2,7 +2,7 @@
 /**
  * Plugin Name: beehiiv
  * Description: Official beehiiv WordPress plugin. Publish posts as newsletters and grow your audience with beehiiv.
- * Version: 1.0.2
+ * Version: 1.1.0
  * Author: beehiiv
  * Text Domain: beehiiv
  * Domain Path: /languages
@@ -18,7 +18,7 @@
 defined( 'ABSPATH' ) || exit;
 
 if ( ! defined( 'BEEHIIV_VERSION' ) ) {
-	define( 'BEEHIIV_VERSION', '1.0.2' );
+	define( 'BEEHIIV_VERSION', '1.1.0' );
 }
 
 if ( ! defined( 'BEEHIIV_PLUGIN_FILE' ) ) {

composer.json

@@ -8,6 +8,9 @@
 			"Beehiiv\\": "includes/"
 		}
 	},
+	"scripts": {
+		"test": "phpunit -c phpunit.xml.dist"
+	},
 	"minimum-stability": "stable",
 	"require": {
 		"php": ">=7.4"

includes/API/Cache.php

@@ -91,6 +91,18 @@ public static function set_publications( array $items ): void {
 		set_transient( self::PUBLICATIONS_KEY, $items, self::TTL );
 	}
 
+	/**
+	 * Clear the cached publications list so the next read fetches it from beehiiv.
+	 *
+	 * @since x.x.x
+	 *
+	 * @return void
+	 */
+	public static function delete_publications(): void {
+
+		delete_transient( self::PUBLICATIONS_KEY );
+	}
+
 	/**
 	 * Cached templates for a publication.
 	 *

includes/API/Client.php

@@ -41,6 +41,13 @@ final class Client {
 	 */
 	private static $allow_retry = true;
 
+	/**
+	 * Retry-After header from the most recent response, in seconds, if any.
+	 *
+	 * @var int|null
+	 */
+	private static $last_retry_after = null;
+
 	/**
 	 * HTTP timeout in seconds for beehiiv API requests.
 	 *
@@ -51,13 +58,14 @@ final class Client {
 	/**
 	 * Make an authenticated GET request to beehiiv v2.
 	 *
-	 * @param string              $path Relative API path (e.g. `/publications`).
-	 * @param array<string,mixed> $query Query parameters.
+	 * @param string              $path    Relative API path (e.g. `/publications`).
+	 * @param array<string,mixed> $query   Query parameters.
+	 * @param int                 $timeout HTTP timeout in seconds; 0 uses the default.
 	 * @return array<string, mixed>
 	 * @since 1.0.0
 	 */
-	public static function request( string $path, array $query = [] ): array {
-		return self::send( 'GET', $path, $query, null );
+	public static function request( string $path, array $query = [], int $timeout = 0 ): array {
+		return self::send( 'GET', $path, $query, null, $timeout );
 	}
 
 	/**
@@ -80,6 +88,16 @@ public static function get_last_wp_error(): ?string {
 		return self::$last_wp_error;
 	}
 
+	/**
+	 * Retry-After header from the most recent response, in seconds.
+	 *
+	 * @return int|null Null when the response had no numeric Retry-After header.
+	 * @since 1.0.0
+	 */
+	public static function get_last_retry_after(): ?int {
+		return self::$last_retry_after;
+	}
+
 	/**
 	 * Make an authenticated POST request with a JSON body.
 	 *
@@ -125,10 +143,11 @@ public static function patch( string $path, array $body, array $query = [] ): ar
 	 * @param string                   $path   Relative API path.
 	 * @param array<string,mixed>      $query  Query parameters.
 	 * @param array<string,mixed>|null $body   JSON body for POST and PATCH; null for GET and DELETE.
+	 * @param int                      $timeout HTTP timeout in seconds; 0 uses the default.
 	 * @return array<string, mixed>
 	 * @since 1.0.0
 	 */
-	private static function send( string $method, string $path, array $query, ?array $body ): array {
+	private static function send( string $method, string $path, array $query, ?array $body, int $timeout = 0 ): array {
 
 		$access_token = Manager::get_access_token();
 		$url          = OAuthConfig::get_api_base_url() . $path;
@@ -139,7 +158,7 @@ private static function send( string $method, string $path, array $query, ?array
 
 		$args = [
 			'method'    => $method,
-			'timeout'   => self::REQUEST_TIMEOUT,
+			'timeout'   => $timeout > 0 ? $timeout : self::REQUEST_TIMEOUT,
 			'sslverify' => OAuthConfig::should_verify_ssl(),
 			'headers'   => [
 				'Authorization' => 'Bearer ' . $access_token,
@@ -157,6 +176,10 @@ private static function send( string $method, string $path, array $query, ?array
 		self::$last_status_code = is_wp_error( $res ) ? null : (int) wp_remote_retrieve_response_code( $res );
 		self::$last_wp_error    = is_wp_error( $res ) ? $res->get_error_message() : null;
 
+		self::$last_retry_after = is_wp_error( $res )
+			? null
+			: self::parse_retry_after( wp_remote_retrieve_header( $res, 'retry-after' ) );
+
 		$raw  = is_wp_error( $res ) ? '' : (string) wp_remote_retrieve_body( $res );
 		$json = json_decode( $raw, true );
 
@@ -165,12 +188,35 @@ private static function send( string $method, string $path, array $query, ?array
 			$refreshed         = TokenRefresher::refresh();
 
 			if ( ! is_wp_error( $refreshed ) ) {
-				return self::send( $method, $path, $query, $body );
+				return self::send( $method, $path, $query, $body, $timeout );
 			}
 		}
 
 		self::$allow_retry = true;
 
 		return is_array( $json ) ? $json : [];
 	}
+
+	/**
+	 * Seconds to wait from a Retry-After header, given as seconds or as an HTTP date.
+	 *
+	 * @param string|array<int,string> $value Header value.
+	 * @return int|null Seconds (0 or more), or null when absent or unparsable.
+	 * @since 1.0.0
+	 */
+	private static function parse_retry_after( $value ): ?int {
+		$value = is_array( $value ) ? (string) reset( $value ) : trim( (string) $value );
+
+		if ( '' === $value ) {
+			return null;
+		}
+
+		if ( is_numeric( $value ) ) {
+			return max( 0, (int) $value );
+		}
+
+		$timestamp = strtotime( $value );
+
+		return false === $timestamp ? null : max( 0, $timestamp - time() );
+	}
 }