feat: adds interfaces for provider-based operations

Author: JasonTheAdams

src/Providers/Contracts/ProviderOperationsHandlerInterface.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Contracts;
+
+use InvalidArgumentException;
+use WordPress\AiClient\Operations\DTO\GenerativeAiOperation;
+
+/**
+ * Interface for handling provider-level operations.
+ *
+ * Provides methods to retrieve and manage long-running operations
+ * across all models within a provider. Operations are tracked at the
+ * provider level rather than per-model.
+ *
+ * @since n.e.x.t
+ */
+interface ProviderOperationsHandlerInterface
+{
+    /**
+     * Gets an operation by ID.
+     *
+     * @since n.e.x.t
+     *
+     * @param string $operationId Operation identifier.
+     * @return GenerativeAiOperation The operation.
+     * @throws InvalidArgumentException If operation not found.
+     */
+    public function getOperation(string $operationId): GenerativeAiOperation;
+}

src/Providers/Contracts/ProviderWithOperationsHandlerInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Contracts;
+
+/**
+ * Interface for providers that support operations handlers.
+ *
+ * Providers implementing this interface can return an operations handler
+ * for managing long-running operations across all their models.
+ *
+ * @since n.e.x.t
+ */
+interface ProviderWithOperationsHandlerInterface
+{
+    /**
+     * Gets the operations handler for this provider.
+     *
+     * @since n.e.x.t
+     *
+     * @return ProviderOperationsHandlerInterface The operations handler.
+     */
+    public static function operationsHandler(): ProviderOperationsHandlerInterface;
+}