From 40793cd4bb1ddcd8d6eac62bee4653c34b4c97a1 Mon Sep 17 00:00:00 2001
From: Keith Solomon <ksolomon@gmail.com>
Date: Sun, 9 Aug 2026 23:06:24 -0500
Subject: [PATCH] Add provider-aware helpers; mark legacy wrappers deprecated

---
 includes/helper-functions.php | 69 +++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/includes/helper-functions.php b/includes/helper-functions.php
index 819db86..5e3bb3a 100644
--- a/includes/helper-functions.php
+++ b/includes/helper-functions.php
@@ -41,6 +41,67 @@ function projects_portfolio_settings() {
     return $settings;
 }
 
+/**
+ * Fetch normalized repository data for a project.
+ *
+ * @since  1.1.0
+ * @param  int    $post_id
+ * @return array|null
+ */
+function projects_portfolio_get_repo_data( int $post_id ): ?array {
+    return projects_portfolio_get_provider( $post_id )->get_repo_data();
+}
+
+/**
+ * Resolve the latest release ZIP download URL for a project.
+ *
+ * @since  1.1.0
+ * @param  int $post_id
+ * @return string|null
+ */
+function projects_portfolio_get_release_url( int $post_id ): ?string {
+    return projects_portfolio_get_provider( $post_id )->get_release_url();
+}
+
+/**
+ * Fetch the latest tag name for a project.
+ *
+ * @since  1.1.0
+ * @param  int    $post_id
+ * @return string
+ */
+function projects_portfolio_get_version( int $post_id ): string {
+    return projects_portfolio_get_provider( $post_id )->get_latest_version();
+}
+
+/**
+ * Fetch the repo owner profile data for a project.
+ *
+ * @since  1.1.0
+ * @param  int    $post_id
+ * @return array|null
+ */
+function projects_portfolio_get_owner( int $post_id ): ?array {
+    $provider = projects_portfolio_get_provider( $post_id );
+    $repo     = $provider->get_repo_data();
+    $login    = $repo['owner']['login'] ?? '';
+    if ( '' === $login ) {
+        return null;
+    }
+    return $provider->get_owner_data( $login );
+}
+
+/**
+ * Public browse URL for the project's repo.
+ *
+ * @since  1.1.0
+ * @param  int    $post_id
+ * @return string
+ */
+function projects_portfolio_get_repo_browse_url( int $post_id ): string {
+    return projects_portfolio_get_provider( $post_id )->get_repo_browse_url();
+}
+
 /**
  * GitHub API call for owner data
  *
@@ -50,6 +111,8 @@ function projects_portfolio_settings() {
  * @return mixed
  */
 function projects_portfolio_github_owner( $owner_name = NULL ) {
+    _deprecated_function( __FUNCTION__, '1.1.0', 'projects_portfolio_get_owner( $post_id )' );
+
     if ( ! $owner_name ) { return; }
 
     $owner = 'https://api.github.com/users/' . $owner_name;
@@ -87,6 +150,8 @@ function projects_portfolio_github_owner( $owner_name = NULL ) {
  * @return mixed
  */
 function projects_portfolio_get_github_release_url( $github_url ) {
+    _deprecated_function( __FUNCTION__, '1.1.0', 'projects_portfolio_get_release_url( $post_id )' );
+
     $api_token = get_option( 'projects_portfolio_github_api_token', '' );
     $api_url   = str_replace( 'https://github.com/', 'https://api.github.com/repos/', rtrim( $github_url, '/' ) ) . '/releases/latest';
 
@@ -126,6 +191,8 @@ function projects_portfolio_get_github_release_url( $github_url ) {
  * @return array|null Associative array of GitHub repo data on success, or null on failure.
  */
 function projects_portfolio_get_github_data( $github_url ) {
+    _deprecated_function( __FUNCTION__, '1.1.0', 'projects_portfolio_get_repo_data( $post_id )' );
+
     if ( empty( $github_url ) ) {
         error_log( 'GitHub URL is empty.' );
         return null;
@@ -186,6 +253,8 @@ function projects_portfolio_get_github_data( $github_url ) {
  * @return string The version number or 'Unknown'.
  */
 function projects_portfolio_get_version_from_github( $github_url ) {
+    _deprecated_function( __FUNCTION__, '1.1.0', 'projects_portfolio_get_version( $post_id )' );
+
     if ( empty( $github_url ) ) {
         return 'Unknown';
     }