Commit 1a: Cloudflare Workers AI image provider + pricing + validator (#9)

Implements image-provider interface + Cloudflare Workers AI adapter with pricing and validator. Independent QA verdict: APPROVE on 52fd11e (qa-reviews/prautoblogger/2026-04-15-52fd11e2ce97dd9e659df5cc87ec1382a668bec1.md). All 4 CTO blockers resolved (PHPUnit retry mocks, XSS hardening on error strings, PHPCS on new files, 300-line cap via support-class extraction). PHPCS backlog (586 errors across 38 pre-existing files) remains on continue-on-error; Workstream C material.
2026-04-15 18:25:46 +07:00
parent 2d75051967
commit 8e6b2d528f
12 changed files with 1231 additions and 1 deletions
--- a/includes/providers/interface-image-provider.php
+++ b/includes/providers/interface-image-provider.php
@@ -0,0 +1,100 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Contract for any image generation provider (Cloudflare Workers AI, DALL-E, etc.).
+ *
+ * Consumers depend on this interface, never on a concrete provider — swapping
+ * providers means writing one new class, not refactoring the pipeline. This
+ * mirrors the LLM provider pattern in `interface-llm-provider.php` (see CTO
+ * rule #7 — interface for external service integrations).
+ *
+ * Triggered by: PRAutoBlogger_Image_Pipeline (added in commit #1b) during the
+ *               content generation run, after editorial review, before publish.
+ * Dependencies: None at interface level — implementations wrap a specific HTTP API.
+ *
+ * @see class-cloudflare-image-provider.php — Default implementation (FLUX.1 via Workers AI).
+ * @see interface-llm-provider.php          — Parallel pattern for LLM providers.
+ * @see ARCHITECTURE.md                     — External API Integrations table.
+ */
+interface PRAutoBlogger_Image_Provider_Interface {
+
+	/**
+	 * Generate a single image from a prompt at the requested dimensions.
+	 *
+	 * Implementations MUST:
+	 *   - Apply retry + exponential backoff on transient failures (5xx, network).
+	 *   - Fail loudly on client errors (4xx) rather than silently returning empty.
+	 *   - Log each attempt via PRAutoBlogger_Logger.
+	 *   - Persist a structured event row via PRAutoBlogger_Event_Log (added in a
+	 *     later commit — safe to no-op until then).
+	 *
+	 * Side effects: HTTP request to the provider API.
+	 *
+	 * @param string $prompt Full prompt (concept + style suffix already concatenated).
+	 * @param int    $width  Target width in pixels (>= 64, <= 2048).
+	 * @param int    $height Target height in pixels (>= 64, <= 2048).
+	 * @param array{
+	 *     seed?: int,
+	 *     steps?: int,
+	 *     model?: string,
+	 * } $options Optional tuning. `seed` lets the caller ask for visually
+	 *           coherent variants across placements. `steps` trades quality
+	 *           for cost (default model-dependent). `model` picks a specific
+	 *           model identifier; implementations may ignore values they
+	 *           don't support.
+	 *
+	 * @return array{
+	 *     bytes: string,
+	 *     mime_type: string,
+	 *     width: int,
+	 *     height: int,
+	 *     model: string,
+	 *     seed: ?int,
+	 *     cost_usd: float,
+	 *     latency_ms: int,
+	 * } Raw image bytes (PNG or JPEG) plus metadata. Metadata is used by the
+	 *   caller to write post meta and to bill against the plugin's cost budget.
+	 *
+	 * @throws \RuntimeException On API error after retries exhausted, or on
+	 *                            an invalid response shape.
+	 * @throws \InvalidArgumentException If dimensions are out of range.
+	 */
+	public function generate_image( string $prompt, int $width, int $height, array $options = [] ): array;
+
+	/**
+	 * Estimate the USD cost of a single generation call before making it.
+	 *
+	 * Used by the cost tracker to pre-check budget and to show an expected
+	 * spend figure in the dry-run preview.
+	 *
+	 * @param int   $width  Target width in pixels.
+	 * @param int   $height Target height in pixels.
+	 * @param array $options Same shape as generate_image() options.
+	 *
+	 * @return float Estimated cost in USD for a single image at the given dimensions.
+	 */
+	public function estimate_cost( int $width, int $height, array $options = [] ): float;
+
+	/**
+	 * Machine-readable provider identifier used in logs and settings.
+	 *
+	 * @return string Lowercase identifier, e.g. 'cloudflare_workers_ai'.
+	 */
+	public function get_provider_name(): string;
+
+	/**
+	 * Verify the provider credentials are present and the API is reachable.
+	 *
+	 * Used by the admin "Test Connections" action. Implementations should make
+	 * a lightweight request (e.g. a models list or token verify endpoint) — NOT
+	 * generate a real image.
+	 *
+	 * Side effects: HTTP request, logs the result.
+	 *
+	 * @return array{status: string, message: string, debug?: string}
+	 *         status is 'ok' or 'error'; message is human-readable for the
+	 *         admin UI; debug is optional diagnostic detail for logs.
+	 */
+	public function validate_credentials_detailed(): array;
+}