typekit-client 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b2d0603ce4ff30ecb04ccf846ba94cf71b0e8d54
-  data.tar.gz: a85ce05a15a5aa3b0cea5b1e0122ccd0b8db6eb8
+  metadata.gz: 4e6cca3a1c8d723d09a5e4e08c7c2f6826a7d820
+  data.tar.gz: be86c255f7b3e9009e51c2e90a14174763d93827
 SHA512:
-  metadata.gz: a661e632bae645066c291a078fdd60ce727d137e3bd5edf4778dbe5dad1554f18e1f88d99c4dbbea0bc92e09d042c7486c64c30fa77e3984ac3b0145e40d6f38
-  data.tar.gz: 60bfc3980c3128be77545fb6be4e8d88edd436b773f30a09cc930868f666b001ea1227e2c6e5bcbb17e7790273fa48f0df0e3c644b8426b8f140ca469e890404
+  metadata.gz: 5fcecc1eb0c187932be93338cae4a888e5eb099ec4963fa4a7df99bcd7c1dad8dcde686d3a8bd25f4809f1cc4716784b1b982642c09e6d30e5cc2a801b2a9335
+  data.tar.gz: 6216034d76d6480dc17b5d1849e9a2f0ae28f035a33e5fac2e4e1b657189a03e793b179587c64c1b2883e0925527f41273dbd58a00d0d984baebc4b937cfbc43

data/.gitignore

@@ -1,5 +1,7 @@
-*.swp
 .DS_Store
-Gemfile.lock
-*.gem
+*.swp
 *.swo
+*.gem
+Gemfile.lock
+doc
+.yardoc

data/.travis.yml

@@ -1,6 +1,10 @@
 language: ruby
+
 rvm:
+  - 1.9.3
+  - 2.0.0
   - 2.1.0
+
 branches:
   only:
     - master

data/.yardopts

@@ -0,0 +1,6 @@
+--markup-provider=redcarpet
+--markup=markdown
+lib/**/*.rb
+-
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -1,19 +1,31 @@
+## Typekit Client 0.0.6 (July 29, 2014)
+
+* Implementation of an Active-Record-like architecture: each Typekit resource
+  (kits, families, libraries, and variations) is ascribed a Ruby class that
+  provides various methods for manipulating the corresponding data (`Kit.all`,
+  `Kit.find`, `kit.save`, `kit.delete`, etc.).
+* Support for Ruby >= 1.9.3 instead of Ruby >= 2.1.
+
 ## Typekit Client 0.0.5 (June 10, 2014)
+
 * New name for the general CLI: `typekit-client` instead of `typekit`.
 * New CLI for the sole purpose of publishing kits: `typekit-publisher`.
 * Relations between resources (a kit has families, a family has variations,
   a variation belongs to a family, etc.).
 
 ## Typekit Client 0.0.4 (June 1, 2014)
+
 * Extraction of the RESTful API logic into a separate gem called
   [Apitizer](https://github.com/IvanUkhov/apitizer).
 * Elimination of the `--version` and `--format` options of the CLI.
 
 ## Typekit Client 0.0.3 (May 31, 2014)
+
 * Object-restful mapping (families, kits, etc. got proper classes).
 * Command history and tab completion in the CLI.
 
 ## Typekit Client 0.0.2 (May 28, 2014)
+
 * New name for the gem (still `require 'typekit'`).
 * Basic DSL for describing RESTful resources.
 * Client-side verification of user requests.

data/Guardfile

@@ -1,8 +1,8 @@
-guard :rspec do
+guard :rspec, cmd: 'bundle exec rspec' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^spec/.+_helper\.rb$}) { 'spec' }
   watch(%r{^lib/(.+)\.rb$}) do |match|
-    result = "spec/#{ match[1] }_spec.rb"
+    result = "spec/lib/#{match[1]}_spec.rb"
     begin
       break if File.exist?(result)
       result = File.dirname(result)
@@ -10,7 +10,7 @@ guard :rspec do
     result
   end
   watch(%r{^lib/[^/]+/(.+)\.rb$}) do |match|
-    result = "spec/features/#{ match[1] }"
+    result = "spec/features/#{match[1]}"
     begin
       break if File.exist?(result)
       result = File.dirname(result)
@@ -18,4 +18,22 @@ guard :rspec do
     result
   end
 end
+
+require 'guard/plugin'
+
+module ::Guard
+  class Whatever < ::Guard::Plugin
+    def run_all; end
+    def run_on_changes(*); end
+  end
+end
+
+guard :whatever do
+  watch(%r{^lib/.*\.rb$})
+  watch(%r{^.*\.md$})
+
+  callback(:run_all_end) { system 'yardoc' }
+  callback(:run_on_changes_end) { system 'yardoc' }
+end
+
 # vim: ft=ruby

data/README.md

@@ -1,300 +1,303 @@
-# Typekit Client [![Gem Version](https://badge.fury.io/rb/typekit-client.svg)](http://badge.fury.io/rb/typekit-client) [![Build Status](https://travis-ci.org/IvanUkhov/typekit-client.svg?branch=master)](https://travis-ci.org/IvanUkhov/typekit-client)
+# Typekit Client [![Gem Version](https://badge.fury.io/rb/typekit-client.svg)](http://badge.fury.io/rb/typekit-client) [![Dependency Status](https://gemnasium.com/IvanUkhov/typekit-client.svg)](https://gemnasium.com/IvanUkhov/typekit-client) [![Build Status](https://travis-ci.org/IvanUkhov/typekit-client.svg?branch=master)](https://travis-ci.org/IvanUkhov/typekit-client)
+
 A Ruby library for accessing the [Typekit API](https://typekit.com/docs/api).
 
 ## Installation
-The minimal supported version of Ruby is `2.1`. The simplest way to install
-Ruby is via [rvm](https://rvm.io/):
-```bash
-$ curl -sSL https://get.rvm.io | bash -s stable --ruby=2.1
-```
 
-Now you can install the library itself:
-```bash
-$ gem install typekit-client
-```
+In your `Gemfile`:
 
-If you are planning to use the gem as a part of your project, add the
-following line into your `Gemfile`:
 ```ruby
 gem 'typekit-client', require: 'typekit'
 ```
 
-Then execute:
+In your terminal:
+
 ```bash
 $ bundle
 ```
 
-In order to interact with the Typekit API, one should have a valid API token.
-You can generate such a token [here](https://typekit.com/account/tokens).
-For convenience, let us create a shortcut for it:
-```bash
-$ export tk_token=YOUR_TOKEN_GOES_HERE
-```
+## TL;DR
+
+Here are some typical use cases of the gem:
 
-## Usage
-Here is the basic setup in a Ruby script:
 ```ruby
 require 'typekit'
 
 client = Typekit::Client.new(token: ENV['tk_token'])
+
+# List all kits
+kits = client::Kit.all
+
+# Find a kit by id
+kit = client::Kit.find('bas4cfe')
+
+# Create a kit
+kit = client::Kit.create(name: 'Megakit', domains: ['localhost'],
+  families: [{ id: 'vcsm', subset: 'all', variations: ['n4'] }])
+
+# Update a kit
+kit.update(name: 'Ultrakit', families: [{ id: 'vybr' }])
+
+# Publish a kit
+kit.publish
+
+# Delete a kit
+kit.delete
+
+# Find a font family by id
+family = client::Family.find('vybr')
+
+# Find a font family by slug
+family = client::Family.find('calluna')
+
+# List all font libraries
+libraries = client::Library.all
+
+# Find a library by id and retrieve its first ten font families
+library = client::Library.find('trial', page: 1, per_page: 10)
 ```
 
-`client` has five methods: `index`, `show`, `create`, `update`, and `delete`.
-The signature of each method is `action(*path, parameters = {})`. The
-arguments are as follows:
-* `*path` refers to an arbitrary number of arguments needed to identify
-  the endpoint of interest (a plenty of examples are given below);
-* `parameters` is a hash of parameters (optional).
+## Preliminaries
 
-Before sending the actual request to the Typekit API, the library checks
-whether the endpoint given by `*path` exists and, if it does, whether
-the desired action (`index`, `show`, _etc._) is permitted. So, if you
-receive an exception, check the [API reference](https://typekit.com/docs/api/).
+The Typekit API provides four major resources: kits, font families, font
+variations, and font libraries. The operations concerning kits require
+authentication. To this end, one has to have a valid API token. Such a token
+can be generated on [Your API Tokens](https://typekit.com/account/tokens) on
+Typekit. For convenience, the examples on this page assume that a valid API
+token is stored in an environment variable called `tk_token`.
+
+The four resources are mapped to the following Ruby classes, respectively:
+
+* `Typekit::Record::Kit`,
+* `Typekit::Record::Family`,
+* `Typekit::Record::Variation`, and
+* `Typekit::Record::Library`.
+
+Each resource has its own set of permitted operations. The entire routing map
+is as follows:
 
-Now, let us have a look at some typical use cases. For clarity, the code
-below makes use of the following auxiliary function:
 ```ruby
-def p(data)
-  puts JSON.pretty_generate(data)
-rescue JSON::GeneratorError
-  puts data.inspect
+resources :kits do
+  resources :families, only: [:show, :update, :delete]
+  show :published, on: :member
+  update :publish, on: :member
 end
+
+resources :families, only: :show do
+  show ':variation', on: :member
+end
+
+resources :libraries, only: [:index, :show]
 ```
 
-### List all kits
-Code:
+Here, the DSL of [Apitizer](https://github.com/IvanUkhov/apitizer) is utilized,
+which is similar to the one of
+[Rails](http://guides.rubyonrails.org/routing.html).
+
+Refer to the [official documentation](https://typekit.com/docs/api) of the
+Typekit API to get a complete description of each endpoint.
+
+## High-Level Programming Interface
+
+The preferable way to work with the four Ruby classes given earlier is via
+an instance of `Typekit::Client` as a module:
+
+* `client::Kit`,
+* `client::Family`,
+* `client::Variation`, and
+* `client::Library`.
+
+The kits that are available under your account can be listed as follows:
+
 ```ruby
-p kits = client.index(:kits)
-p kits.map(&:class)
-p kits.first.attributes
-p kits.first.link
+kits = client::Kit.all
 ```
 
-Output:
-```json
-[
-  {
-    "id": "bas4cfe",
-    "link": "/api/v1/json/kits/bas4cfe"
-  },
-  {
-    "id": "sfh6bkj",
-    "link": "/api/v1/json/kits/sfh6bkj"
-  },
-  {
-    "id": "kof8zcn",
-    "link": "/api/v1/json/kits/kof8zcn"
-  }
-]
-[
-  "Typekit::Record::Kit",
-  "Typekit::Record::Kit",
-  "Typekit::Record::Kit"
-]
-{
-  "id": "bas4cfe",
-  "link": "/api/v1/json/kits/bas4cfe"
-}
-"/api/v1/json/kits/bas4cfe"
-```
+Each kit is an instance of `Typekit::Record::Kit`, and it contains all
+attributes that the Typekit API returns in response to the corresponding
+API call. In the case of `all`, the Typekit API provides only two attribute,
+namely, `id` and `link`; such kits will be referred to as incomplete.
+Here is an example:
 
-### Show the description of a variation of a font family
-Code:
 ```ruby
-p client.show(:families, 'vcsm', 'i9')
-```
+kit.complete?
+# => false
 
-Output:
-```json
-{
-  "id": "vcsm:i9",
-  "name": "Proxima Nova Black Italic",
-  "family": {
-    "id": "vcsm",
-    "link": "/api/v1/json/families/vcsm",
-    "name": "Proxima Nova"
-  },
-  "font_style": "italic",
-  "font_variant": "normal",
-  "font_weight": "900",
-  ...
-}
+kit.attributes
+# =>
+# {
+#   "id": "bas4cfe",
+#   "link": "/api/v1/json/kits/bas4cfe"
+# }
+
+kit.id
+# => "bas4cfe"
+
+kit.link
+# => "/api/v1/json/kits/bas4cfe"
 ```
 
-### Show the font families in the trial library with pagination
-Code:
+A particular kit can be fetched using its `id`:
+
 ```ruby
-p client.show(:libraries, 'trial', page: 10, per_page: 5)
+kit = client::Kit.find('bas4cfe') # or find! to raise an exception if failed
 ```
 
-Output:
-```json
-{
-  "id": "trial",
-  "link": "/api/v1/json/libraries/trial",
-  "name": "Trial Library",
-  "families": [
-    {
-      "id": "qnhl",
-      "link": "/api/v1/json/families/qnhl",
-      "name": "Caliban Std"
-    },
-    {
-      "id": "vybr",
-      "link": "/api/v1/json/families/vybr",
-      "name": "Calluna"
-    },
-    ...
-  ],
-  "pagination": {
-    "count": 261,
-    "on": "families",
-    "page": 10,
-    "page_count": 53,
-    "per_page": 5
-  }
-}
-```
+In the case of `find`, you get all information about the kit:
 
-### Create a new kit
-Code:
 ```ruby
-p kit = client.create(:kits, name: 'Megakit', domains: 'localhost')
-```
+kit.complete?
+# => true
+
+kit.attributes
+# =>
+# {
+#   "id": "bas4cfe",
+#   "name": "Megakit",
+#   "analytics": false,
+#   "domains": [
+#     "localhost"
+#   ],
+#   "families": [
+#     ...
+#   ]
+# }
 
-Output:
-```json
-{
-  "id": "izw0qiq",
-  "name": "Megakit",
-  "analytics": false,
-  "badge": true,
-  "domains": [
-    "localhost"
-  ],
-  "families": [
-
-  ]
-}
+kit.name
+# => "Megakit"
 ```
 
-### Disable the badge of a kit
-Code:
+In order to reload a kit and/or retrieve missing data, call `load`:
+
 ```ruby
-p client.update(:kits, kit.id, badge: false)
-```
+kit.complete?
+# => false
 
-Output:
-```json
-{
-  "id": "izw0qiq",
-  "name": "Megakit",
-  "analytics": false,
-  "badge": false,
-  "domains": [
-    "localhost"
-  ],
-  "families": [
-
-  ]
-}
+kit.load # or load! to raise an exception if failed
+
+kit.complete?
+# => true
 ```
 
-### Look up the id of a font family by its slug
-Code:
+In order to change an attribute of a kit, assign a new value to that
+attribute and call `save`:
+
 ```ruby
-p family = client.show(:families, 'proxima-nova')
+kit.name = 'Ultrakit'
+kit.save # or save! to raise an exception if failed
 ```
 
-Output:
-```json
-{
-  "id": "vcsm",
-  "link": "/api/v1/json/families/vcsm"
-}
-```
+Similarly, the `families` attribute, containing the font families included in
+the kit, can be changed as desired:
 
-### Add a font family into a kit
-Code:
 ```ruby
-p client.update(:kits, kit.id, families: { "0" => { id: family.id } })
-```
+# Push a new instance of Typekit::Record::Family
+kit.families << Typekit::Record::Family.new(id: 'vybr')
+
+# Push a hash of attributes
+kit.families << { id: 'vcsm', subset: 'all' }
+
+# Replace with an font family found via client
+kit.families = [client::Family.find('droid-sans')]
 
-Output:
-```json
-{
-  "id": "nys8sny",
-  "name": "Megakit",
-  "analytics": false,
-  "badge": false,
-  "domains": [
-    "localhost"
-  ],
-  "families": [
-    {
-      "id": "vcsm",
-      "name": "Proxima Nova",
-      "slug": "proxima-nova",
-      "css_names": [
-        "proxima-nova-1",
-        "proxima-nova-2"
-      ],
-      ...
-    }
-  ]
-}
+# Remove all font families
+kit.families = []
+
+kit.save
 ```
 
-### Publish a kit
-Code:
+If you want to browse the font families hosted on Typekit, you can do so via
+libraries. All libraries can be listed as follows:
+
 ```ruby
-p client.update(:kits, kit.id, :publish)
+libraries = client::Library.all
 ```
 
-Output:
-```
-#<DateTime: 2014-05-31T06:45:29+00:00 ((2456809j,24329s,0n),+0s,2299161j)>
-```
+A particular library can be fetched using:
 
-### Show the description of a published kit
-Code:
 ```ruby
-p client.show(:kits, kit.id, :published)
+library = client::Library.find('trial')
 ```
 
-Output:
-```json
-{
-  "id": "vzt4lrg",
-  "name": "Megakit",
-  "analytics": false,
-  "badge": false,
-  "domains": [
-    "localhost"
-  ],
-  "families": [
-    ...
-  ],
-  "published": "2014-05-31T06:45:29Z"
-}
-```
+In this case, along with some general information about the library itself, the
+Typekit API will return a subset of the font families included in the library
+according to its default pagination. The desired pagination can be specified as
+follows:
 
-### Delete a kit
-Command:
 ```ruby
-p client.delete(:kits, kit.id)
+library = client::Library.find('trial', page: 1, per_page: 10)
 ```
 
-Output:
-```
-true
+The font families are stored in the `families` attribute of the library.
+
+## Low-Level Programming Interface
+
+An instance of `Typekit::Client` has a method called `process` that can be
+used to perform arbitrary API calls. The signature of the method is
+`process(action, *enpoint, parameters = {})`, and the arguments are as follows:
+
+* `action` is one of `:index`, `:show`, `:create`, `:update`, and `:delete`;
+* `*endpoint` refers to an arbitrary number of arguments needed to identify
+  the endpoint of interest;
+* `parameters` is a optional hash of parameters.
+
+Each of the five actions has a shortcut: instead of calling
+`client.process(action, *endpoint, parameters)`, you can just call
+`client.action(*endpoint, parameters)` replacing `action` with `index`, `show`,
+`create`, `update`, or `delete`.
+
+Here are some examples:
+
+```ruby
+require 'typekit'
+
+client = Typekit::Client.new(token: ENV['tk_token'])
+
+# List all kits
+kits = client.index(:kits)
+
+# Find a kit by id
+kit = client.show(:kits, 'bas4cfe')
+
+# Create a kit
+kit = client.create(:kits, name: 'Megakit', domains: ['localhost'],
+  families: [{ id: 'vcsm', subset: 'all', variations: ['n4'] }])
+
+# Update a kit
+client.update(:kits, 'bas4cfe', name: 'Ultrakit', families: [{ id: 'vybr' }])
+
+# Publish a kit
+client.update(:kits, 'bas4cfe', :publish)
+
+# Delete a kit
+client.delete(:kits, 'bas4cfe')
+
+# Find a font family by id
+family = client.show(:families, 'vybr')
+
+# Find a font family by slug
+family = client.show(:families, 'calluna')
+
+# Show a font family in a kit by id
+family = client.show(:kits, 'bas4cfe', :families, 'vcsm')
+
+# Show a variation of a font family by id
+variation = client.show(:families, 'vybr', 'i4')
+
+# List all font libraries
+libraries = client.index(:libraries)
+
+# Find a library by id and retrieve its first ten font families
+library = client.show(:libraries, 'trial', page: 1, per_page: 10)
 ```
 
-## General Command-line Interface
-There is a simple tool provided in order to demonstrate the usage of the
-library and to give the ability to perform basic operations without writing
-any code. The tool is called `typekit-client`, and it should get installed
-along with the gem. Try running:
+## Low-Level Command-Line Interface
+
+There is a command-line tool provided in order to interact with the Typekit
+API without writing any code.  The tool is called `typekit-client`, and
+its capabilities directly reflect the low-level programming interface describe
+earlier:
+
 ```
 $ typekit-client -h
 Usage: typekit-client [options] [command]
@@ -306,14 +309,9 @@ Other options:
     -h, --help                       Show this message
 ```
 
-Alternatively, you can install `typekit-client` in the `bin` directory of
-your project using the following command:
-```bash
-$ bundle binstubs typekit-client
-```
-
 The tool has two modes: normal and interactive. If `command` is provided,
 the tool executes only that particular command and terminates:
+
 ```
 $ typekit-client -t $tk_token index kits
 [
@@ -328,6 +326,7 @@ $
 
 If `command` is not provided, the tool gives a command prompt wherein one
 can enter multiple commands:
+
 ```
 $ typekit-client -t $tk_token
 Type 'help' for help and 'exit' to exit.
@@ -335,17 +334,18 @@ Type 'help' for help and 'exit' to exit.
 Usage: <action> <resource> [parameters]
 
     <action>        index, show, create, update, or delete
-    <resource>      a list separated by whitespaces
+    <endpoint>      a list separated by whitespaces
     [parameters]    a JSON-encoded hash (optional)
 
 Examples:
     index kits
-    show kits bas4cfe families vcsm
-    show families vcsm i9
-    show libraries trial { "page": 10, "per_page": 5 }
-    create kits { "name": "Megakit", "domains": "localhost" }
-    update kits bas4cfe { "name": "Ultrakit" }
+    create kits { "name": "Megakit", domains: ["localhost"] }
+    show kits bas4cfe
+    update kits bas4cfe { families: [{ "id": "vybr" }] }
+    update kits bas4cfe publish
     delete kits bas4cfe
+    show families vybr i4
+    show libraries trial { "page": 10, "per_page": 5 }
 > index kits
 [
   {
@@ -359,7 +359,8 @@ Bye.
 $
 ```
 
-## Publishing Command-line Interface
+## Publishing Command-Line Interface
+
 There is another utility with the sole purpose of publishing kits. The tool
 is called `typekit-publisher`:
 
@@ -389,11 +390,15 @@ Publishing bas4cfe... Done.
 Publishing sfh6bkj... Done.
 Publishing kof8zcn... Done.
 Bye.
+$
 ```
 
 ## Contributing
-1. Fork it ( https://github.com/IvanUkhov/typekit-client/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+
+1. [Fork](https://help.github.com/articles/fork-a-repo) the project.
+2. Create a branch for your feature (`git checkout -b awesome-feature`).
+3. Implement your feature (`vim`).
+4. Commit your changes (`git commit -am 'Implemented an awesome feature'`).
+5. Push to the branch (`git push origin awesome-feature`).
+6. [Create](https://help.github.com/articles/creating-a-pull-request)
+   a new Pull Request.