From 25df6996e6f3165ef3c412c3f97b80fe3489c31c Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Mon, 9 Mar 2026 17:25:40 +0000
Subject: [PATCH] feat(plug): add contract interfaces and Registry::register()
 method

Move 8 plug contract interfaces (Authenticable, Commentable, Deletable,
Listable, MediaUploadable, Postable, Readable, Refreshable) from the
Laravel app into the framework under Core\Plug\Contract namespace. Add
register() method to Registry so extracted packages can self-register
their providers without filesystem scanning.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 src/Plug/Contract/Authenticable.php   | 45 +++++++++++++++++++++++++++
 src/Plug/Contract/Commentable.php     | 22 +++++++++++++
 src/Plug/Contract/Deletable.php       | 18 +++++++++++
 src/Plug/Contract/Listable.php        | 21 +++++++++++++
 src/Plug/Contract/MediaUploadable.php | 20 ++++++++++++
 src/Plug/Contract/Postable.php        | 23 ++++++++++++++
 src/Plug/Contract/Readable.php        | 25 +++++++++++++++
 src/Plug/Contract/Refreshable.php     | 20 ++++++++++++
 src/Plug/Registry.php                 | 15 +++++++++
 9 files changed, 209 insertions(+)
 create mode 100644 src/Plug/Contract/Authenticable.php
 create mode 100644 src/Plug/Contract/Commentable.php
 create mode 100644 src/Plug/Contract/Deletable.php
 create mode 100644 src/Plug/Contract/Listable.php
 create mode 100644 src/Plug/Contract/MediaUploadable.php
 create mode 100644 src/Plug/Contract/Postable.php
 create mode 100644 src/Plug/Contract/Readable.php
 create mode 100644 src/Plug/Contract/Refreshable.php

diff --git a/src/Plug/Contract/Authenticable.php b/src/Plug/Contract/Authenticable.php
new file mode 100644
index 0000000..4389077
--- /dev/null
+++ b/src/Plug/Contract/Authenticable.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Core\Plug\Contract;
+
+use Core\Plug\Response;
+
+/**
+ * Contract for authentication operations.
+ *
+ * Covers OAuth2, API key, webhook, and credential-based auth flows.
+ */
+interface Authenticable
+{
+    /**
+     * Get provider identifier (e.g., 'twitter', 'bluesky').
+     */
+    public static function identifier(): string;
+
+    /**
+     * Get display name (e.g., 'X', 'Bluesky').
+     */
+    public static function name(): string;
+
+    /**
+     * Get OAuth authorisation URL.
+     *
+     * Returns empty string if not OAuth-based.
+     */
+    public function getAuthUrl(): string;
+
+    /**
+     * Exchange credentials/callback params for access token.
+     *
+     * @param  array  $params  OAuth callback params or credentials
+     * @return array Token data or error
+     */
+    public function requestAccessToken(array $params): array;
+
+    /**
+     * Get authenticated account information.
+     */
+    public function getAccount(): Response;
+}
diff --git a/src/Plug/Contract/Commentable.php b/src/Plug/Contract/Commentable.php
new file mode 100644
index 0000000..26916df
--- /dev/null
+++ b/src/Plug/Contract/Commentable.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Core\Plug\Contract;
+
+use Core\Plug\Response;
+
+/**
+ * Contract for comment/reply operations.
+ */
+interface Commentable
+{
+    /**
+     * Post a comment or reply to existing content.
+     *
+     * @param  string  $text  Comment content
+     * @param  string  $postId  ID of the post to comment on
+     * @param  array  $params  Platform-specific options
+     */
+    public function comment(string $text, string $postId, array $params = []): Response;
+}
diff --git a/src/Plug/Contract/Deletable.php b/src/Plug/Contract/Deletable.php
new file mode 100644
index 0000000..22e5565
--- /dev/null
+++ b/src/Plug/Contract/Deletable.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Core\Plug\Contract;
+
+use Core\Plug\Response;
+
+/**
+ * Contract for content deletion operations.
+ */
+interface Deletable
+{
+    /**
+     * Delete a post by its external ID.
+     */
+    public function delete(string $id): Response;
+}
diff --git a/src/Plug/Contract/Listable.php b/src/Plug/Contract/Listable.php
new file mode 100644
index 0000000..5e25281
--- /dev/null
+++ b/src/Plug/Contract/Listable.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Core\Plug\Contract;
+
+use Core\Plug\Response;
+
+/**
+ * Contract for listing entities (pages, boards, publications, etc.).
+ *
+ * Used by providers that require selecting a target entity before posting.
+ * Examples: Meta pages, Pinterest boards, Medium publications.
+ */
+interface Listable
+{
+    /**
+     * List available entities for the authenticated user.
+     */
+    public function listEntities(): Response;
+}
diff --git a/src/Plug/Contract/MediaUploadable.php b/src/Plug/Contract/MediaUploadable.php
new file mode 100644
index 0000000..1018e41
--- /dev/null
+++ b/src/Plug/Contract/MediaUploadable.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Core\Plug\Contract;
+
+use Core\Plug\Response;
+
+/**
+ * Contract for media upload operations.
+ */
+interface MediaUploadable
+{
+    /**
+     * Upload media to the platform.
+     *
+     * @param  array  $item  Media item with 'path', 'mime_type', 'name', etc.
+     */
+    public function upload(array $item): Response;
+}
diff --git a/src/Plug/Contract/Postable.php b/src/Plug/Contract/Postable.php
new file mode 100644
index 0000000..7a51d29
--- /dev/null
+++ b/src/Plug/Contract/Postable.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Core\Plug\Contract;
+
+use Core\Plug\Response;
+use Illuminate\Support\Collection;
+
+/**
+ * Contract for content publishing operations.
+ */
+interface Postable
+{
+    /**
+     * Publish content to the platform.
+     *
+     * @param  string  $text  Post content
+     * @param  Collection  $media  Media items (may be empty)
+     * @param  array  $params  Platform-specific options
+     */
+    public function publish(string $text, Collection $media, array $params = []): Response;
+}
diff --git a/src/Plug/Contract/Readable.php b/src/Plug/Contract/Readable.php
new file mode 100644
index 0000000..6289071
--- /dev/null
+++ b/src/Plug/Contract/Readable.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Core\Plug\Contract;
+
+use Core\Plug\Response;
+
+/**
+ * Contract for reading posts and content.
+ */
+interface Readable
+{
+    /**
+     * Get a single post by ID.
+     */
+    public function get(string $id): Response;
+
+    /**
+     * Get multiple posts (timeline/feed).
+     *
+     * @param  array  $params  Pagination and filter options
+     */
+    public function list(array $params = []): Response;
+}
diff --git a/src/Plug/Contract/Refreshable.php b/src/Plug/Contract/Refreshable.php
new file mode 100644
index 0000000..326f2ee
--- /dev/null
+++ b/src/Plug/Contract/Refreshable.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Core\Plug\Contract;
+
+use Core\Plug\Response;
+
+/**
+ * Contract for token refresh operations.
+ */
+interface Refreshable
+{
+    /**
+     * Refresh an expired access token.
+     *
+     * @return Response Contains new token data on success
+     */
+    public function refresh(): Response;
+}
diff --git a/src/Plug/Registry.php b/src/Plug/Registry.php
index 67ba112..0561496 100644
--- a/src/Plug/Registry.php
+++ b/src/Plug/Registry.php
@@ -67,6 +67,21 @@ class Registry
         $this->discovered = true;
     }
 
+    /**
+     * Register a provider programmatically.
+     *
+     * Used by plug packages to self-register without filesystem scanning.
+     */
+    public function register(string $identifier, string $category, string $name, string $namespace): void
+    {
+        $this->providers[$identifier] = [
+            'category' => $category,
+            'name' => $name,
+            'namespace' => $namespace,
+            'path' => null,
+        ];
+    }
+
     /**
      * Get all registered provider identifiers.
      *