yt-core 0.0.1 → 0.1.0

data/docs/index.html

@@ -0,0 +1,37 @@
+---
+title:  "Installing Yt"
+h2: "Installing Yt"
+---
+
+<p>Add Yt to any bundled Ruby project by adding the line <code>gem 'yt', '~> {{ page.version }}'</code> to its Gemfile.</p>
+<p>You can also install Yt in your system by opening the Terminal and typing <code>gem install yt</code>.</p>
+<p>If you need to update version, type <code>gem update yt</code>, or run <code>bundle update</code> if inside a Ruby project.</p>
+
+<hr />
+<h4>Configuring your app</h4>
+
+<p>
+  In order to use the gem, you must register your app in the Google Developers Console.
+</p>
+
+<dl>
+  <dt>Create a project</dt>
+  <dd>
+    Browse to the <a href="https://console.developers.google.com">Google Developers Console</a> and select “Create Project”:
+    <img src="{{ site.baseurl }}/images/console-01.png" width="600" height="420" style="display: block" />
+    From the menu select “API Manager”, then “Credentials”:
+    <img src="{{ site.baseurl }}/images/console-02.png" width="600" height="420" style="display: block" />
+  </dd>
+  <dt><a class="anchor" id="api_key"></a>Generate an API key</dt>
+  <dd>
+    If you are building an app that only retrieves public data from YouTube, all you need is an API key:
+    <img src="{{ site.baseurl }}/images/console-03.png" width="600" height="420" style="display: block" />
+    Once you have generated an API key, you can use it to configure your app:
+    <img src="{{ site.baseurl }}/images/console-04.png" width="600" height="420" style="display: block" />
+    {% highlight ruby %}
+# run this block before using any method of the gem (replace with your key)
+Yt.configure do |config|
+  config.api_key = 'AIzaSyAkHdn_oBEjZIEBlpMiGZP-3Y05NXtrzqY'
+end{% endhighlight %}
+  </dd>
+</dl>

data/docs/playlist_items.html

@@ -0,0 +1,65 @@
+---
+title:  "Yt::PlaylistItem"
+h2: "Playlist items"
+---
+
+<p>
+  <code>Yt::PlaylistItem</code> represents a <a href="https://developers.google.com/youtube/v3/docs/playlistItems">YouTube playlist item</a>.
+  Initialize using its YouTube ID:
+</p>
+
+{% highlight ruby %}
+item = Yt::PlaylistItem.new id: 'UEwtTGVUdXRjOUdSS0Qze'
+# => #<Yt::PlaylistItem:0x... @id=UEwtTGVUdXRjOUdSS0Qze>
+{% endhighlight %}
+
+<hr />
+<h4>Authentication</h4>
+
+<p>
+  Most methods of <code>Yt::PlaylistItem</code> <strong>retrieve public data</strong> from YouTube (e.g.: fetch an item’s position).<br />
+  To use these methods (marked with <span class="label label-success">&nbsp;</span> below), you only need to <a href="{{ site.baseurl }}/#api_key">generate an API key</a> and configure:
+</p>
+
+{% highlight ruby %}
+Yt.configuration.api_key = "<your api key>"                     ## use your API key
+item = Yt::PlaylistItem.new id: 'UEwtTGVUdXRjOUdSS0Qze' ## use any playlist item ID
+item.position # => 0
+{% endhighlight %}
+
+<hr />
+<h4>List of <code>Yt::PlaylistItem</code> data methods</h4>
+<dl>
+  {% include dt.html title="Playlist item’s snippet" label="success" auth="any authentication works" %}
+  <dd><a class="anchor" id="snippet"></a><div class="highlight"><pre>
+{% include doc.html instance="PlaylistItem#id" %}{% include example.html object='item' method='id' result='"UEwtTGVUdXRjOUdSS0Qze"' %}
+{% include doc.html instance="PlaylistItem#title" %}{% include example.html object='item' method='title' result='"First public video"' %}
+{% include doc.html instance="PlaylistItem#description" %}{% include example.html object='item' method='description' result='"A YouTube video to test the yt gem."' %}
+{% include doc.html instance="PlaylistItem#published_at" %}{% include example.html object='item' method='published_at' result='2016-11-18 23:40:55 UTC' %}
+{% include doc.html instance="PlaylistItem#thumbnail_url" %}{% include example.html object='item' method='thumbnail_url' result='"https://i.ytimg.com/vi/gknzFj_0vvY/default.jpg"' %}
+{% include doc.html instance="PlaylistItem#channel_id" %}{% include example.html object='item' method='channel_id' result='"UCwCnUcLcb9-eSrHa_RQGkQQ"' %}
+{% include doc.html instance="PlaylistItem#channel_title" %}{% include example.html object='item' method='channel_title' result='"Yt Test"' %}
+{% include doc.html instance="PlaylistItem#playlist_id" %}{% include example.html object='item' method='playlist_id' result='"PL-LeTutc9GRKD3yBDhnRF_yE8UTaQI5Jf"' %}
+{% include doc.html instance="PlaylistItem#position" %}{% include example.html object='item' method='position' result='0' %}
+{% include doc.html instance="PlaylistItem#video_id" %}{% include example.html object='item' method='video_id' result='"gknzFj_0vvY"' %}</pre>
+  </div></dd>
+
+  {% include dt.html title="Playlist item’s status" label="success" auth="any authentication works" %}
+  <dd><a class="anchor" id="status"></a><div class="highlight"><pre>
+{% include doc.html instance="PlaylistItem#privacy_status" %}{% include example.html object='item' method='privacy_status' result='"public"' %}</pre>
+  </div></dd>
+</dl>
+<p>
+  To limit the number of HTTP requests, use <code>select</code> to specify which <a href="https://developers.google.com/youtube/v3/docs/playlistItems/list#part">parts</a> of the item’s data to load:
+</p>
+<dl>
+  <dd><a class="anchor" id="select"></a><div class="highlight"><pre>
+{% include example.html object='slow = item' result='without select: 2 HTTP requests' %}
+{% include example.html object='slow' method='title' result='one HTTP request to fetch the item’s snippet' %}
+{% include example.html object='slow' method='privacy_status' result='=> another HTTP request to fetch the item’s status' %}
+
+{% include doc.html instance="PlaylistItem#select" %}{% include example.html object='fast = item' method='select' params=' <span class="ss">:snippet</span><span class="p">,</span> <span class="ss">:status</span>' result='with select: 1 HTTP request' %}
+{% include example.html object='fast' method='title' result='one HTTP request to fetch both the item’s snippet and status' %}
+{% include example.html object='fast' method='privacy_status' result='=> no extra HTTP requests' %}</pre>
+  </div></dd>
+</dl>

data/docs/playlists.html

@@ -0,0 +1,114 @@
+---
+title:  "Yt::Playlist"
+h2: "Playlists"
+---
+
+<p>
+  <code>Yt::Playlist</code> represents a <a href="https://developers.google.com/youtube/v3/docs/playlists">YouTube playlist</a>.
+  Initialize using its YouTube ID:
+</p>
+
+<dl>
+  <dd><a class="anchor" id="new"></a><div class="highlight"><pre>
+{% include doc.html instance="Playlist#initialize" %}{% include example.html object='playlist = <span class="no">Yt</span><span class="o">::</span><span class="no">Playlist</span>' method='new' params=' <span class="ss">id:</span> <span class="s1">"PL-LeTutc9GRKD3yBDhnRF_yE8UTaQI5Jf"</span>' %}
+{% include example.html result='#&lt;Yt::Playlist @id=PL-LeTutc9GRKD3yBDhnRF_yE8UTaQI5Jf&gt;' %}
+{% include doc.html instance="Playlist#canonical_url" %}{% include example.html object='playlist' method='canonical_url' %}
+{% include example.html result='"https://www.youtube.com/playlist?list=PL-LeTutc9GRKD3yBDhnRF_yE8UTaQI5Jf"' %}</pre>
+  </div></dd>
+</dl>
+
+<hr />
+<h4>Authentication</h4>
+
+<p>
+  Most methods of <code>Yt::Playlist</code> <strong>retrieve public data</strong> from YouTube (e.g.: fetch a playlist’s title).<br />
+  To use these methods (marked with <span class="label label-success">&nbsp;</span> below), you only need to <a href="{{ site.baseurl }}/#api_key">generate an API key</a> and configure:
+</p>
+
+{% highlight ruby %}
+Yt.configuration.api_key = "<your api key>"                     ## use your API key
+playlist = Yt::Playlist.new id: 'PL-LeTutc9GRKD3yBDhnRF_yE8UTa' ## use any playlist ID
+playlist.title # => "First public playlist"
+{% endhighlight %}
+
+<hr />
+<h4>List of <code>Yt::Playlist</code> data methods</h4>
+<dl>
+  {% include dt.html title="Playlist’s snippet" label="success" auth="any authentication works" %}
+  <dd><a class="anchor" id="snippet"></a><div class="highlight"><pre>
+{% include doc.html instance="Playlist#id" %}{% include example.html object='playlist' method='id' result='"PL-LeTutc9GRKD3yBDhnRF_yE8UTaQI5Jf"' %}
+{% include doc.html instance="Playlist#title" %}{% include example.html object='playlist' method='title' result='"First public playlist"' %}
+{% include doc.html instance="Playlist#description" %}{% include example.html object='playlist' method='description' result='"A YouTube playlist to test the yt gem."' %}
+{% include doc.html instance="Playlist#published_at" %}{% include example.html object='playlist' method='published_at' result='2016-11-18 00:40:02 UTC' %}
+{% include doc.html instance="Playlist#thumbnail_url" %}{% include example.html object='playlist' method='thumbnail_url' result='"https://i.ytimg.com/vi/gknzFj_0vvY/default.jpg"' %}
+{% include doc.html instance="Playlist#channel_id" %}{% include example.html object='playlist' method='channel_id' result='"UCwCnUcLcb9-eSrHa_RQGkQQ"' %}
+{% include doc.html instance="Playlist#channel_title" %}{% include example.html object='playlist' method='channel_title' result='"Yt Test"' %}</pre>
+  </div></dd>
+
+  {% include dt.html title="Playlist’s status" label="success" auth="any authentication works" %}
+  <dd><a class="anchor" id="status"></a><div class="highlight"><pre>
+{% include doc.html instance="Playlist#privacy_status" %}{% include example.html object='playlist' method='privacy_status' result='"public"' %}</pre>
+  </div></dd>
+
+  {% include dt.html title="Playlist’s content details" label="success" auth="any authentication works" %}
+  <dd><a class="anchor" id="content_details"></a><div class="highlight"><pre>
+{% include doc.html instance="Playlist#item_count" %}{% include example.html object='playlist' method='item_count' result='2' %}</pre>
+  </div></dd>
+
+</dl>
+<p>
+  To limit the number of HTTP requests, use <code>select</code> to specify which <a href="https://developers.google.com/youtube/v3/docs/playlists/list#part">parts</a> of the playlist’s data to load:
+</p>
+<dl>
+  <dd><a class="anchor" id="select"></a><div class="highlight"><pre>
+{% include example.html object='slow = playlist' result='without select: 2 HTTP requests' %}
+{% include example.html object='slow' method='title' result='one HTTP request to fetch the playlist’s snippet' %}
+{% include example.html object='slow' method='privacy_status' result='=> another HTTP request to fetch the playlist’s status' %}
+
+{% include doc.html instance="Playlist#select" %}{% include example.html object='fast = playlist' method='select' params=' <span class="ss">:snippet</span><span class="p">,</span> <span class="ss">:status</span>' result='with select: 1 HTTP request' %}
+{% include example.html object='fast' method='title' result='one HTTP request to fetch both the playlist’s snippet and status' %}
+{% include example.html object='fast' method='privacy_status' result='=> no extra HTTP requests' %}</pre>
+  </div></dd>
+</dl>
+
+<dl>
+  {% include dt.html title="Playlist’s items" label="success" auth="any authentication works" %}
+  <dd><a class="anchor" id="items"></a><div class="highlight"><pre>
+{% include doc.html instance="Playlist#items" %}{% include example.html object='playlist' method='items' %}
+{% include example.html result='#&lt;Yt::Relation [#&lt;Yt::PlaylistItem @id=U...&gt;, #&lt;Yt::PlaylistItem @id=T...&gt;, ...]&gt;' %}</pre>
+  </div></dd>
+</dl>
+<dl>
+  {% include dt.html title="Playlist’s videos" label="success" auth="any authentication works" %}
+  <dd><a class="anchor" id="videos"></a><div class="highlight"><pre>
+{% include doc.html instance="Playlist#videos" %}{% include example.html object='playlist' method='videos' %}
+{% include example.html result='#&lt;Yt::Relation [#&lt;Yt::Video @id=gknz...&gt;, #&lt;Yt::Video @id=32Gc...&gt;, ...]&gt;' %}</pre>
+  </div></dd>
+</dl>
+<p>
+  Before iterating through items or videos, use <code>select</code> to specify which <a href="https://developers.google.com/youtube/v3/docs/videos/list#part">parts</a> to load:
+</p>
+<dl>
+  <dd><a class="anchor" id="select"></a><div class="highlight"><pre>
+{% include doc.html instance="Relation#select" %}{% include example.html object='items = playlist.items' method='select' params=' <span class="ss">:snippet</span>, <span class="ss">:status</span>' %}
+{% include example.html object='items' method='map <span class="ss">&amp;:title</span>' result='["First public video", "Second public video", ...]' %}
+{% include example.html object='items' method='map <span class="ss">&amp;:privacy_status</span>' result='["public", "public", ...]' %}</pre>
+  </div></dd>
+</dl>
+<p>
+  You can also use <code>limit</code> to only fetch a certain number of items or videos:
+</p>
+<dl>
+  <dd><a class="anchor" id="limit"></a><div class="highlight"><pre>
+{% include doc.html instance="Relation#limit" %}{% include example.html object='videos = playlist.videos' method='limit' params=' <span class="mi">2</span>' %}
+{% include example.html object='videos' method='map <span class="ss">&amp;:id</span>' result='["gknzFj_0vvY", "oO6WawhsxTA"]' %}</pre>
+  </div></dd>
+</dl>
+<p>
+  You can also use <code>size</code> to quickly obtain the estimated number of items or videos:
+</p>
+<dl>
+  <dd><a class="anchor" id="size"></a><div class="highlight"><pre>
+{% include doc.html instance="Relation#size" %}{% include example.html object='playlist.items' method='size' result='63' %}</pre>
+  </div></dd>
+</dl>

data/docs/urls.html

@@ -0,0 +1,52 @@
+---
+title:  "Yt::URL"
+h2: "URLs"
+---
+
+<p>
+  <code>Yt::URL</code> is a convenience class to identify YouTube resources based on their URL patterns:
+</p>
+
+<dl>
+  <dd><a class="anchor" id="snippet"></a><div class="highlight"><pre>
+{% include doc.html library="yt-url" instance="URL#initialize" %}{% include example.html object='url = <span class="no">Yt</span><span class="o">::</span><span class="no">URL</span>' method='new' params=' <span class="s1">"youtu.be/gknzFj_0vvY"</span>' %}
+{% include doc.html library="yt-url" instance="URL#kind" %}{% include example.html object='url' method='kind' result=':video' %}
+{% include doc.html library="yt-url" instance="URL#id" %}{% include example.html object='url' method='id' result='"gknzFj_0vvY"' %}
+{% include doc.html library="yt-url" instance="URL#resource" %}{% include example.html object='url' method='resource' result='#&lt;Yt::Video @id=gknzFj_0vvY&gt;' %}</pre>
+  </div></dd>
+</dl>
+
+<hr />
+<h4>Configuration</h4>
+
+<p>
+  <code>Yt::URL</code> <strong>is not part of the <code>yt</code> library</strong>, but comes from the <a href="https://github.com/claudiob/yt-url">yt-url</a> extension.
+</p>
+<p>
+  To use in any bundled Ruby project, remember to add the line <code>gem 'yt-url', '~> 0.0.0'</code> to its Gemfile.
+</p>
+
+<hr />
+<h4>Authentication</h4>
+
+<p>
+  Using <code>Yt::URL</code> does not require authentication since it is based on matching a set of hard-coded patterns:
+</p>
+
+{% highlight ruby %}
+Yt::URL::PLAYLIST_PATTERNS # => [
+#   %r{^(?:https?://)?(?:www\.)?youtube\.com/playlist/?\?list=(?<id>[a-zA-Z0-9_-]+)},
+# ]
+
+Yt::URL::VIDEO_PATTERNS # => [
+#   %r{^(?:https?://)?(?:www\.)?youtube\.com/watch\?v=(?<id>[a-zA-Z0-9_-]{11})},
+#   %r{^(?:https?://)?(?:www\.)?youtu\.be/(?<id>[a-zA-Z0-9_-]{11})},
+#   %r{^(?:https?://)?(?:www\.)?youtube\.com/embed/(?<id>[a-zA-Z0-9_-]{11})},
+#   %r{^(?:https?://)?(?:www\.)?youtube\.com/v/(?<id>[a-zA-Z0-9_-]{11})},
+# ]
+
+Yt::URL::CHANNEL_PATTERNS # => [
+#   %r{^(?:https?://)?(?:www\.)?youtube\.com/channel/(?<id>UC[a-zA-Z0-9_-]{22})},
+#   %r{^(?:https?://)?(?:www\.)?youtube\.com/(?<format>c/|user/)?(?<name>[a-zA-Z0-9_-]+)}
+# ]
+{% endhighlight %}

data/docs/videos.html

@@ -0,0 +1,104 @@
+---
+title:  "Yt::Video"
+h2: "Videos"
+---
+
+<p>
+  <code>Yt::Video</code> represents a <a href="https://developers.google.com/youtube/v3/docs/videos">YouTube video</a>.
+  Initialize using its YouTube ID:
+</p>
+
+<dl>
+  <dd><a class="anchor" id="new"></a><div class="highlight"><pre>
+{% include doc.html instance="Video#initialize" %}{% include example.html object='video = <span class="no">Yt</span><span class="o">::</span><span class="no">Video</span>' method='new' params=' <span class="ss">id:</span> <span class="s1">"gknzFj_0vvY"</span>' %}
+{% include example.html result='#&lt;Yt::Video @id=gknzFj_0vvY&gt;' %}
+{% include doc.html instance="Video#canonical_url" %}{% include example.html object='video' method='canonical_url' %}
+{% include example.html result='"https://www.youtube.com/watch?v=gknzFj_0vvY"' %}</pre>
+  </div></dd>
+</dl>
+
+<hr />
+<h4>Authentication</h4>
+
+<p>
+  Most methods of <code>Yt::Video</code> <strong>retrieve public data</strong> from YouTube (e.g.: fetch a video’s title).<br />
+  To use these methods (marked with <span class="label label-success">&nbsp;</span> below), you only need to <a href="{{ site.baseurl }}/#api_key">generate an API key</a> and configure:
+</p>
+
+{% highlight ruby %}
+Yt.configuration.api_key = "<your api key>"                        ## use your API key
+
+video = Yt::Video.new id: 'gknzFj_0vvY'                            ## use any video ID
+video.title # => "First public video"
+{% endhighlight %}
+
+<hr />
+<h4>List of <code>Yt::Video</code> data methods</h4>
+<dl>
+  {% include dt.html title="Video’s snippet" label="success" auth="any authentication works" %}
+  <dd><a class="anchor" id="snippet"></a><div class="highlight"><pre>
+{% include doc.html instance="Video#id" %}{% include example.html object='video' method='id' result='"gknzFj_0vvY"' %}
+{% include doc.html instance="Video#title" %}{% include example.html object='video' method='title' result='"First public video"' %}
+{% include doc.html instance="Video#description" %}{% include example.html object='video' method='description' result='"A YouTube video to test the yt gem."' %}
+{% include doc.html instance="Video#published_at" %}{% include example.html object='video' method='published_at' result='2016-10-20 02:19:05 UTC' %}
+{% include doc.html instance="Video#thumbnail_url" %}{% include example.html object='video' method='thumbnail_url' result='"https://i.ytimg.com/vi/gknzFj_0vvY/default.jpg"' %}
+{% include doc.html instance="Video#channel_id" %}{% include example.html object='video' method='channel_id' result='"UCwCnUcLcb9-eSrHa_RQGkQQ"' %}
+{% include doc.html instance="Video#channel_title" %}{% include example.html object='video' method='channel_title' result='"Yt Test"' %}
+{% include doc.html instance="Video#tags" %}{% include example.html object='video' method='tags' result='["yt", "test", "tag"]' %}
+{% include doc.html instance="Video#category_id" %}{% include example.html object='video' method='category_id' result='22' %}
+{% include doc.html instance="Video#category_title" %}{% include example.html object='video' method='category_title' result='"People & Blogs"' %}
+{% include doc.html instance="Video#live_broadcast_content" %}{% include example.html object='video' method='live_broadcast_content' result='"none"' %}</pre>
+  </div></dd>
+
+  {% include dt.html title="Video’s status" label="success" auth="any authentication works" %}
+  <dd><a class="anchor" id="status"></a><div class="highlight"><pre>
+{% include doc.html instance="Video#privacy_status" %}{% include example.html object='video' method='privacy_status' result='"public"' %}
+{% include doc.html instance="Video#upload_status" %}{% include example.html object='video' method='upload_status' result='"processed"' %}
+{% include doc.html instance="Video#license" %}{% include example.html object='video' method='license' result='"creative_common"' %}
+{% include doc.html instance="Video#embeddable" %}{% include example.html object='video' method='embeddable' result='true' %}
+{% include doc.html instance="Video#public_stats_viewable" %}{% include example.html object='video' method='public_stats_viewable' result='false' %}</pre>
+  </div></dd>
+
+  {% include dt.html title="Video’s statistics" label="success" auth="any authentication works" %}
+  <dd><a class="anchor" id="statistics"></a><div class="highlight"><pre>
+{% include doc.html instance="Video#view_count" %}{% include example.html object='video' method='view_count' result='123' %}
+{% include doc.html instance="Video#like_count" %}{% include example.html object='video' method='like_count' result='93' %}
+{% include doc.html instance="Video#dislike_count" %}{% include example.html object='video' method='dislike_count' result='42' %}
+{% include doc.html instance="Video#comment_count" %}{% include example.html object='video' method='comment_count' result='62' %}</pre>
+  </div></dd>
+
+  {% include dt.html title="Video’s content details" label="success" auth="any authentication works" %}
+  <dd><a class="anchor" id="content_details"></a><div class="highlight"><pre>
+{% include doc.html instance="Video#duration" %}{% include example.html object='video' method='duration' result='"PT2S"' %}
+{% include doc.html instance="Video#seconds" %}{% include example.html object='video' method='seconds' result='2' %}
+{% include doc.html instance="Video#length" %}{% include example.html object='video' method='length' result='"00:00:02"' %}
+{% include doc.html instance="Video#dimension" %}{% include example.html object='video' method='dimension' result='"2d"' %}
+{% include doc.html instance="Video#definition" %}{% include example.html object='video' method='definition' result='"sd"' %}
+{% include doc.html instance="Video#caption" %}{% include example.html object='video' method='caption' result='false' %}
+{% include doc.html instance="Video#licensed_content" %}{% include example.html object='video' method='licensed_content' result='false' %}
+{% include doc.html instance="Video#projection" %}{% include example.html object='video' method='projection' result='"rectangular"' %}</pre>
+  </div></dd>
+
+</dl>
+<p>
+  To limit the number of HTTP requests, use <code>select</code> to specify which <a href="https://developers.google.com/youtube/v3/docs/videos/list#part">parts</a> of the video’s data to load:
+</p>
+<dl>
+  <dd><a class="anchor" id="select"></a><div class="highlight"><pre>
+{% include example.html object='slow = video' result='without select: 2 HTTP requests' %}
+{% include example.html object='slow' method='title' result='one HTTP request to fetch the video’s snippet' %}
+{% include example.html object='slow' method='privacy_status' result='=> another HTTP request to fetch the video’s status' %}
+
+{% include doc.html instance="Video#select" %}{% include example.html object='fast = video' method='select' params=' <span class="ss">:snippet</span><span class="p">,</span> <span class="ss">:status</span>' result='with select: 1 HTTP request' %}
+{% include example.html object='fast' method='title' result='one HTTP request to fetch both the video’s snippet and status' %}
+{% include example.html object='fast' method='privacy_status' result='=> no extra HTTP requests' %}</pre>
+  </div></dd>
+</dl>
+
+<dl>
+  {% include dt.html title="Video’s channel" label="success" auth="any authentication works" %}
+  <dd><a class="anchor" id="channel"></a><div class="highlight"><pre>
+{% include doc.html instance="Video#channel" %}{% include example.html object='video' method='channel' %}
+{% include example.html result='#&lt;Yt::Channel @id=UCwCnUcLcb9-eSrHa_RQGkQQ&gt;' %}</pre>
+  </div></dd>
+</dl>

data/lib/yt/channel.rb

@@ -0,0 +1,127 @@
+module Yt
+  # Provides methods to interact with YouTube channels.
+  # @see https://developers.google.com/youtube/v3/docs/channels
+  class Channel < Resource
+    # @!attribute [r] title
+    # @return [String] the channel’s title.
+    has_attribute :title, in: :snippet
+
+    # @!attribute [r] description
+    # @return [String] the channel’s description.
+    has_attribute :description, in: :snippet
+
+    # @!attribute [r] published_at
+    # @return [Time] the date and time that the channel was created.
+    has_attribute :published_at, in: :snippet, type: Time
+
+    # @!attribute [r] thumbnails
+    # @return [Hash<String, Hash>] the thumbnails associated with the video.
+    has_attribute :thumbnails, in: :snippet
+
+    # @!attribute [r] custom_url
+    # @return [<String, nil>] the path component of the channel’s custom URL.
+    has_attribute :custom_url, in: :snippet
+
+    # has_attribute :default_language, in: :snippet not sure how to set to test
+    # has_attribute :localized, in: :snippet not yet implemented
+    # has_attribute :country, in: :snippet not sure how to set to test
+
+    # @!attribute [r] privacy_status
+    # @return [String] the privacy status of the channel. Valid values are:
+    #   +"private"+, +"public"+, +"unlisted"+.
+    has_attribute :privacy_status, in: :status
+
+    # @!attribute [r] is_linked
+    # @return [Boolean] whether the channel data identifies a user that is
+    #   already linked to either a YouTube username or a Google+ account.
+    has_attribute :is_linked, in: :status
+
+    # @!attribute [r] long_uploads_status
+    # @return [String] whether the channel is eligible to upload videos that
+    #   are more than 15 minutes long. Valid values are: +"allowed"+,
+    #   +"disallowed"+, +"eligible"+, +"longUploadsUnspecified"+.
+    # @note +"longUploadsUnspecified"+ is not documented by the YouTube API.
+    has_attribute :long_uploads_status, in: :status
+
+    # @!attribute [r] view_count
+    # @return [<Integer>] the number of times the channel has been viewed.
+    has_attribute :view_count, in: :statistics, type: Integer
+
+    # @!attribute [r] comment_count
+    # @return [<Integer>] the number of comments for the channel.
+    has_attribute :comment_count, in: :statistics, type: Integer
+
+    # @!attribute [r] subscriber_count
+    # @return [<Integer>] the number of subscribers that the channel has.
+    has_attribute :subscriber_count, in: :statistics, type: Integer
+
+    # @!attribute [r] hidden_subscriber_count
+    # @return [<Boolean>] whether the channel’s subscriber count is publicly
+    #   visible.
+    has_attribute :hidden_subscriber_count, in: :statistics
+
+    # @!attribute [r] video_count
+    # @return [<Integer>] the number of videos uploaded to the channel.
+    has_attribute :video_count, in: :statistics, type: Integer
+
+    # @!attribute [r] banner_image_url
+    # @return [String] the URL for the banner image shown on the channel page
+    #   on the YouTube website. The image is 1060px by 175px.
+    has_attribute :banner_image_url, in: %i(branding_settings image)
+
+    # @!attribute [r] keywords
+    # @return [Array<String>] the keywords associated with the channel.
+    has_attribute :keywords, in: %i(branding_settings channel) do |keywords|
+      (keywords || '').split ' '
+    end
+
+    # @!attribute [r] unsubscribed_trailer
+    # @return [<String, nil>] if specified, the ID of a public or unlisted video
+    #   owned by the channel owner that should play in the featured video module
+    #   in the channel page’s browse view for unsubscribed viewers.
+    has_attribute :unsubscribed_trailer, in: %i(branding_settings channel)
+
+    # @return [String] the canonical form of the channel’s URL.
+    def canonical_url
+      "https://www.youtube.com/channel/#{id}"
+    end
+
+    # @return [<String] the full channel’s URL (custom or canonical).
+    # @see https://support.google.com/youtube/answer/2657968
+    def vanity_url
+      if custom_url
+        "https://www.youtube.com/#{custom_url}"
+      else
+        canonical_url
+      end
+    end
+
+    # Returns the URL of one of the channel’s thumbnail.
+    # @param [Symbol, String] size The size of the channel’s thumbnail.
+    # @return [String] if +size+ is +:default+, the URL of a 88x88px image.
+    # @return [String] if +size+ is +:medium+, the URL of a 240x240px image.
+    # @return [String] if +size+ is +:high+, the URL of a 800x800px image.
+    # @return [nil] if the +size+ is none of the above.
+    def thumbnail_url(size = :default)
+      thumbnails.fetch(size.to_s, {})['url']
+    end
+
+    # @return [Yt::Relation<Yt::Video>] the public videos of the channel.
+    # @note For unauthenticated channels, results are constrained to a maximum
+    # of 500 videos.
+    # @see https://developers.google.com/youtube/v3/docs/search/list#channelId
+    def videos
+      @videos ||= Relation.new(Video, channel_id: id, limit: 500) do |options|
+        items = fetch '/youtube/v3/search', channel_videos_params(options)
+        videos_for items, 'id', options
+      end
+    end
+
+    # @return [Yt::Relation<Yt::Playlist>] the public playlists of the channel.
+    def playlists
+      @playlists ||= Relation.new(Playlist, channel_id: id) do |options|
+        fetch '/youtube/v3/playlists', channel_playlists_params(options)
+      end
+    end
+  end
+end

data/lib/yt/core/version.rb

@@ -0,0 +1,8 @@
+module Yt
+  # Provides basic functionality to connect to the YouTube API.
+  module Core
+    # @return [String] the SemVer-compatible gem version.
+    # @see http://semver.org
+    VERSION = '0.1.0'
+  end
+end

data/lib/yt/core.rb

@@ -0,0 +1,18 @@
+require 'json' # for JSON.parse
+
+require 'yt/config'
+require 'yt/no_items_error'
+require 'yt/http_request'
+require 'yt/relation'
+require 'yt/resource'
+require 'yt/response'
+
+require 'yt/channel'
+require 'yt/playlist'
+require 'yt/playlist_item'
+require 'yt/video'
+
+# An object-oriented Ruby client for YouTube.
+# @see http://www.rubydoc.info/gems/yt/
+module Yt
+end

data/lib/yt/no_items_error.rb

@@ -0,0 +1,8 @@
+module Yt
+  # Raised when items are expected from YouTube but none are returned.
+  # @example Fetch the title of a channel with an unknown ID.
+  #   Yt::Channel.new(id: 'unknown-id').title
+  #   # => raise Yt::NoItemsError
+  class NoItemsError < StandardError
+  end
+end