From 2c954631ca44567dc1af826744843823defedca0 Mon Sep 17 00:00:00 2001
From: alphayax <alphayax@gmail.com>
Date: Sat, 28 May 2016 09:46:33 +0200
Subject: [PATCH] Add Download RSS Feed API

---
 README.md                                     |   1 +
 TODO.md                                       |   2 +-
 .../v3/models/Download/Feed/DownloadFeed.php  | 144 ++++++++++++++
 .../models/Download/Feed/DownloadFeedItem.php | 148 +++++++++++++++
 freebox/api/v3/services/download/Feed.php     | 176 ++++++++++++++++++
 .../api/v3/symbols/Download/Feed/Status.php   |  19 ++
 6 files changed, 489 insertions(+), 1 deletion(-)
 create mode 100644 freebox/api/v3/models/Download/Feed/DownloadFeed.php
 create mode 100644 freebox/api/v3/models/Download/Feed/DownloadFeedItem.php
 create mode 100644 freebox/api/v3/services/download/Feed.php
 create mode 100644 freebox/api/v3/symbols/Download/Feed/Status.php

diff --git a/README.md b/README.md
index ebe401a..9535902 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,7 @@ Jusqu'a présent, les fonctionalités suivantes ont été implémentées :
     - Download Stats
     - Download Files
     - Download Configuration
+    - RSS Feed
     - Bittorent 
         - Trackers
         - Peers
diff --git a/TODO.md b/TODO.md
index d037ba1..0cb29ee 100644
--- a/TODO.md
+++ b/TODO.md
@@ -5,7 +5,7 @@
     - ~~Download Trackers [UNSTABLE]~~
     - ~~Download Peers [UNSTABLE]~~
     - ~~Download Blacklist [UNSTABLE]~~
-    - Download Feeds
+    - ~~Download Feeds~~
     - ~~Download Configuration~~
 - ~~File System Api~~
     - ~~File System~~
diff --git a/freebox/api/v3/models/Download/Feed/DownloadFeed.php b/freebox/api/v3/models/Download/Feed/DownloadFeed.php
new file mode 100644
index 0000000..3834220
--- /dev/null
+++ b/freebox/api/v3/models/Download/Feed/DownloadFeed.php
@@ -0,0 +1,144 @@
+<?php
+namespace alphayax\freebox\api\v3\models\Download\Feed;
+use alphayax\freebox\api\v3\Model;
+
+/**
+ * Class DownloadFeed
+ * @package alphayax\freebox\api\v3\models\Download\Feed
+ */
+class DownloadFeed extends Model {
+
+    /** @var int (Read-only) : id */
+    protected $id;
+
+    /**
+     * @var string (Read-only)
+     * @see Status
+     */
+    protected $status;
+
+    /** @var string (Read-only) : Feed URL */
+    protected $url;
+
+    /** @var string (Read-only) : Feed title (extracted from the RSS) */
+    protected $title;
+
+    /** @var string (Read-only) : Feed description (extracted from the RSS) */
+    protected $desc;
+
+    /** @var string (Read-only) : Feed image URL (extracted from the RSS) */
+    protected $image_url;
+
+    /** @var int (Read-only) : Number of read items in the feed */
+    protected $nb_read;
+
+    /** @var int (Read-only) : Number of unread items in the feed */
+    protected $nb_unread;
+
+    /** @var bool : If set to true, the downloader will automatically download new items */
+    protected $auto_download;
+
+    /** @var int timestamp (Read-only) : Last time the feed was fetched */
+    protected $fetch_ts;
+
+    /** @var int timestamp (Read-only) : Last time the feed was published on remote server */
+    protected $pub_ts;
+
+    /**
+     * @var string (Read-only) : Error code (same as used in Download or DownloadFile).
+     * @see alphayax\freebox\api\v3\symbols\Download\File\Error
+     */
+    protected $error;
+
+    /**
+     * @return int
+     */
+    public function getId() {
+        return $this->id;
+    }
+
+    /**
+     * @return string
+     */
+    public function getStatus() {
+        return $this->status;
+    }
+
+    /**
+     * @return string
+     */
+    public function getUrl() {
+        return $this->url;
+    }
+
+    /**
+     * @return string
+     */
+    public function getTitle() {
+        return $this->title;
+    }
+
+    /**
+     * @return string
+     */
+    public function getDesc() {
+        return $this->desc;
+    }
+
+    /**
+     * @return string
+     */
+    public function getImageUrl() {
+        return $this->image_url;
+    }
+
+    /**
+     * @return int
+     */
+    public function getNbRead() {
+        return $this->nb_read;
+    }
+
+    /**
+     * @return int
+     */
+    public function getNbUnread() {
+        return $this->nb_unread;
+    }
+
+    /**
+     * @return boolean
+     */
+    public function isAutoDownload() {
+        return $this->auto_download;
+    }
+
+    /**
+     * @param boolean $auto_download
+     */
+    public function setAutoDownload( $auto_download) {
+        $this->auto_download = $auto_download;
+    }
+
+    /**
+     * @return int
+     */
+    public function getFetchTs() {
+        return $this->fetch_ts;
+    }
+
+    /**
+     * @return int
+     */
+    public function getPubTs() {
+        return $this->pub_ts;
+    }
+
+    /**
+     * @return string
+     */
+    public function getError() {
+        return $this->error;
+    }
+
+}
diff --git a/freebox/api/v3/models/Download/Feed/DownloadFeedItem.php b/freebox/api/v3/models/Download/Feed/DownloadFeedItem.php
new file mode 100644
index 0000000..b1044ec
--- /dev/null
+++ b/freebox/api/v3/models/Download/Feed/DownloadFeedItem.php
@@ -0,0 +1,148 @@
+<?php
+namespace alphayax\freebox\api\v3\models\Download\Feed;
+use alphayax\freebox\api\v3\Model;
+
+/**
+ * Class DownloadFeedItem
+ * @package alphayax\freebox\api\v3\models\Download\Feed
+ */
+class DownloadFeedItem extends Model {
+
+    /** @var int (Read-only) : id */
+    protected $id;
+
+    /** @var int (Read-only) : id of the DownloadFeed */
+    protected $feed_id;
+
+    /** @var string (Read-only) : item title */
+    protected $title;
+
+    /** @var string (Read-only) : item description */
+    protected $desc;
+
+    /** @var string (Read-only) : item author */
+    protected $author;
+
+    /** @var string (Read-only) : URL of the RSS feed attachment */
+    protected $link;
+
+    /** @var bool : you can mark the item as read manually, or it is marked as read automatically when the item is downloaded */
+    protected $is_read;
+
+    /** @var bool (Read-only) : mark downloaded items, automatically set to true when RSS item is downloaded */
+    protected $is_downloaded;
+
+    /** @var int timestamp (Read-only) : timestamp of the item creation */
+    protected $fetch_ts;
+
+    /** @var int timestamp (Read-only) : item publish timestamp */
+    protected $pub_ts;
+
+    /** @var string (Read-only) : enclosure URL (if specified in RSS feed) */
+    protected $enclosure_url;
+
+    /** @var string (Read-only) : enclosure mime type (if specified in RSS feed) */
+    protected $enclosure_type;
+
+    /** @var int (Read-only) : enclosure size in bytes (if specified in RSS feed) */
+    protected $enclosure_length;
+
+    /**
+     * @return int
+     */
+    public function getId() {
+        return $this->id;
+    }
+
+    /**
+     * @return int
+     */
+    public function getFeedId() {
+        return $this->feed_id;
+    }
+
+    /**
+     * @return string
+     */
+    public function getTitle() {
+        return $this->title;
+    }
+
+    /**
+     * @return string
+     */
+    public function getDesc() {
+        return $this->desc;
+    }
+
+    /**
+     * @return string
+     */
+    public function getAuthor() {
+        return $this->author;
+    }
+
+    /**
+     * @return string
+     */
+    public function getLink() {
+        return $this->link;
+    }
+
+    /**
+     * @return boolean
+     */
+    public function isRead() {
+        return $this->is_read;
+    }
+
+    /**
+     * @param boolean $is_read
+     */
+    public function setRead( $is_read) {
+        $this->is_read = $is_read;
+    }
+
+    /**
+     * @return boolean
+     */
+    public function isIsDownloaded() {
+        return $this->is_downloaded;
+    }
+
+    /**
+     * @return int
+     */
+    public function getFetchTs() {
+        return $this->fetch_ts;
+    }
+
+    /**
+     * @return int
+     */
+    public function getPubTs() {
+        return $this->pub_ts;
+    }
+
+    /**
+     * @return string
+     */
+    public function getEnclosureUrl() {
+        return $this->enclosure_url;
+    }
+
+    /**
+     * @return string
+     */
+    public function getEnclosureType() {
+        return $this->enclosure_type;
+    }
+
+    /**
+     * @return int
+     */
+    public function getEnclosureLength() {
+        return $this->enclosure_length;
+    }
+
+}
diff --git a/freebox/api/v3/services/download/Feed.php b/freebox/api/v3/services/download/Feed.php
new file mode 100644
index 0000000..d641c55
--- /dev/null
+++ b/freebox/api/v3/services/download/Feed.php
@@ -0,0 +1,176 @@
+<?php
+namespace alphayax\freebox\api\v3\services\download;
+use alphayax\freebox\api\v3\Service;
+use alphayax\freebox\api\v3\models;
+
+/**
+ * Class Feed
+ * @package alphayax\freebox\api\v3\services\download
+ */
+class Feed extends Service {
+
+    const API_DOWNLOAD_FEEDS                    = '/api/v3/downloads/feeds/';
+    const API_DOWNLOAD_FEEDS_FETCH              = '/api/v3/downloads/feeds/fetch';
+    const API_DOWNLOAD_FEEDS_ITEM               = '/api/v3/downloads/feeds/%u';
+    const API_DOWNLOAD_FEEDS_ITEM_FETCH         = '/api/v3/downloads/feeds/%u/fetch';
+    const API_DOWNLOAD_FEEDS_ITEMS              = '/api/v3/downloads/feeds/%u/items/';
+    const API_DOWNLOAD_FEEDS_ITEMS_ITEM         = '/api/v3/downloads/feeds/%u/items/%u';
+    const API_DOWNLOAD_FEEDS_ITEMS_ITEM_DOWNLOAD= '/api/v3/downloads/feeds/%u/items/%u/download';
+    const API_DOWNLOAD_FEEDS_ITEMS_MARK_AS_READ = '/api/v3/downloads/feeds/%u/items/mark_all_as_read';
+
+    /**
+     * Get the list of all download Feeds
+     * @throws \Exception
+     * @return models\Download\Feed\DownloadFeed[]
+     */
+    public function getAllFeeds(){
+        $rest = $this->getAuthService( self::API_DOWNLOAD_FEEDS);
+        $rest->GET();
+
+        $DownloadFeed_xs = @$rest->getCurlResponse()['result'] ?: [];
+        $DownloadFeeds   = [];
+        foreach( $DownloadFeed_xs as $DownloadFeed_x) {
+            $DownloadFeeds[] = new models\Download\Feed\DownloadFeed( $DownloadFeed_x);
+        }
+        return $DownloadFeeds;
+    }
+
+    /**
+     * Gets the DownloadFeed with the given id
+     * @param int $downloadFeedId
+     * @return models\Download\Feed\DownloadFeed
+     */
+    public function getFeedFromId( $downloadFeedId){
+        $service = sprintf( self::API_DOWNLOAD_FEEDS_ITEM, $downloadFeedId);
+        $rest = $this->getAuthService( $service);
+        $rest->GET();
+
+        return new models\Download\Feed\DownloadFeed( $rest->getCurlResponse()['result']);
+    }
+
+    /**
+     * Add a Download Feed
+     * @param int $downloadFeedUrl
+     * @return models\Download\Feed\DownloadFeed
+     */
+    public function addFeed( $downloadFeedUrl){
+        $rest = $this->getAuthService( self::API_DOWNLOAD_FEEDS);
+        $rest->POST([
+            'url' => $downloadFeedUrl,
+        ]);
+
+        return new models\Download\Feed\DownloadFeed( $rest->getCurlResponse()['result']);
+    }
+
+    /**
+     * Delete a Download Feed
+     * @param int $downloadFeedId
+     * @return bool
+     */
+    public function removeFeed( $downloadFeedId){
+        $service = sprintf( self::API_DOWNLOAD_FEEDS_ITEM, $downloadFeedId);
+        $rest = $this->getAuthService( $service);
+        $rest->DELETE();
+
+        return (bool) $rest->getCurlResponse()['success'];
+    }
+
+    /**
+     * Update a Download Feed
+     * @param \alphayax\freebox\api\v3\models\Download\Feed\DownloadFeed $downloadFeed
+     * @return \alphayax\freebox\api\v3\models\Download\Feed\DownloadFeed
+     */
+    public function updateFeed(models\Download\Feed\DownloadFeed $downloadFeed){
+        $service = sprintf( self::API_DOWNLOAD_FEEDS_ITEM, $downloadFeed->getId());
+        $rest = $this->getAuthService( $service);
+        $rest->PUT( $downloadFeed->toArray());
+
+        return new models\Download\Feed\DownloadFeed( $rest->getCurlResponse()['result']);
+    }
+
+    /**
+     * Remotely fetches the RSS feed and updates it.
+     * Note that if the remote feed specifies a TTL, trying to update before the ttl will result in feed_is_recent error
+     * @param int $downloadFeedId
+     * @return bool
+     */
+    public function refreshFeed($downloadFeedId){
+        $service = sprintf( self::API_DOWNLOAD_FEEDS_ITEM_FETCH, $downloadFeedId);
+        $rest = $this->getAuthService( $service);
+        $rest->POST();
+
+        return (bool) $rest->getCurlResponse()['success'];
+    }
+
+    /**
+     * Remotely fetches the RSS feed and updates it.
+     * Note that if the remote feed specifies a TTL, trying to update before the ttl will result in feed_is_recent error
+     * @return bool
+     */
+    public function refreshFeeds(){
+        $rest = $this->getAuthService( self::API_DOWNLOAD_FEEDS_FETCH);
+        $rest->POST();
+
+        return (bool) $rest->getCurlResponse()['success'];
+    }
+
+    /**
+     * Returns the collection of all DownloadFeedItems for a given DownloadFeed
+     * @param $downloadFeedId
+     * @return \alphayax\freebox\api\v3\models\Download\Feed\DownloadFeedItem[]
+     */
+    public function getFeedItems( $downloadFeedId){
+        $service = sprintf( self::API_DOWNLOAD_FEEDS_ITEMS, $downloadFeedId);
+        $rest = $this->getAuthService( $service);
+        $rest->GET();
+
+        $DownloadFeedItem_xs = @$rest->getCurlResponse()['result'] ?: [];
+        $DownloadFeedItems   = [];
+        foreach( $DownloadFeedItem_xs as $DownloadFeedItem_x) {
+            $DownloadFeedItems[] = new models\Download\Feed\DownloadFeedItem( $DownloadFeedItem_x);
+        }
+        return $DownloadFeedItems;
+    }
+
+    /**
+     * Returns the collection of all DownloadFeedItems for a given DownloadFeed
+     * @param                                                                $downloadFeedId
+     * @param \alphayax\freebox\api\v3\models\Download\Feed\DownloadFeedItem $DownloadFeedItem
+     * @return bool
+     */
+    public function updateFeedItem( $downloadFeedId, models\Download\Feed\DownloadFeedItem $DownloadFeedItem){
+        $service = sprintf( self::API_DOWNLOAD_FEEDS_ITEMS_ITEM, $downloadFeedId, $DownloadFeedItem->getId());
+        $rest = $this->getAuthService( $service);
+        $rest->PUT( $DownloadFeedItem->toArray());
+
+        return (bool) $rest->getCurlResponse()['success'];
+    }
+
+    /**
+     * Returns the collection of all DownloadFeedItems for a given DownloadFeed
+     * @param                                                                $downloadFeedId
+     * @param \alphayax\freebox\api\v3\models\Download\Feed\DownloadFeedItem $DownloadFeedItem
+     * @return bool
+     */
+    public function downloadFeedItem( $downloadFeedId, models\Download\Feed\DownloadFeedItem $DownloadFeedItem){
+        $service = sprintf( self::API_DOWNLOAD_FEEDS_ITEMS_ITEM_DOWNLOAD, $downloadFeedId, $DownloadFeedItem->getId());
+        $rest = $this->getAuthService( $service);
+        $rest->POST( $DownloadFeedItem->toArray());
+
+        return (bool) $rest->getCurlResponse()['success'];
+    }
+
+    /**
+     * Returns the collection of all DownloadFeedItems for a given DownloadFeed
+     * @param int $downloadFeedId
+     * @return bool
+     */
+    public function markFeedAsRead( $downloadFeedId){
+        $service = sprintf( self::API_DOWNLOAD_FEEDS_ITEMS_MARK_AS_READ, $downloadFeedId);
+        $rest = $this->getAuthService( $service);
+        $rest->POST();
+
+        return (bool) $rest->getCurlResponse()['success'];
+    }
+
+}
diff --git a/freebox/api/v3/symbols/Download/Feed/Status.php b/freebox/api/v3/symbols/Download/Feed/Status.php
new file mode 100644
index 0000000..bae99e4
--- /dev/null
+++ b/freebox/api/v3/symbols/Download/Feed/Status.php
@@ -0,0 +1,19 @@
+<?php
+namespace alphayax\freebox\api\v3\symbols\Download\Feed;
+
+/**
+ * Symbol Status
+ * @package alphayax\freebox\api\v3\symbols\Download\Feed
+ * @see alphayax\freebox\api\v3\models\Download\Feed\DownloadFeed
+ */
+interface Status {
+
+    /** feed is up to date */
+    const READY = 'ready';
+
+    /** feed is updating */
+    const FETCHING = 'fetching';
+
+    /** there was an error trying to refresh this feed, see error */
+    const ERROR = 'error';
+}