# capgun.io API gem

A Ruby wrapper for the capgun.io web thumb service API

## Installation

  gem install capgun

## Credits

The capgun's gem organization is based (and inspired!) by jnunemaker's
[https://github.com/jnunemaker/twitter][twitter gem], see LICENSE.md.
jnunemaker's style of coding is very elegant in its simplicity and a joy to
read.

## Configuration

The gem is easy to configure with the global configure block.  Its most basic
invocation needs to set the authorization token issued to the API.

```ruby
Capgun.configure do |config|
  config.auth_token = "YOUR-AUTH-TOKEN"
end
```

The configuration has the following attributes to be assigned values.

* adapter
* connection_options
* endpoint
* gateway
* auth_token
* user_agent
* proxy

## Actions

There are five actions exposed by the capgun gem.

1. account
1. estimate
1. capture
1. status
1. order

## account

Fetches the account owner's information.

```ruby
# returns a Capgun::Account object
account = Capgun.account
# attributes: id, :name, :balance
account.balance
```

example JSON responses from the capgun service.

```shell
curl -H 'Authorization: abc123' 'https://api.capgun.io/v1/account'
```

```json
{
  "account": {
    "id": "vexuq9ff",
    "name": "Acme Co.",
    "notify": "http://example.com/notify",
    "balance": 200,
    "created_at": "2012-06-08T05:55:39+00:00",
    "updated_at": "2012-06-08T05:55:39+00:00"
  }
}
```


## estimate

An estimate is an order that has not been executed.  It lists the assets that
will be delivered in the order and its cost.

```ruby
# returns a Capgun::Order object
estimate = Capgun.estimate("http://www.google.com/")
# attributes: url, notify, cost, viewport, packages, images, options
estimate.cost
```

example JSON responses from the capgun service.

```shell
curl -H 'Authorization: abc123' \
     --data '{"url":"http://rubygems.org/"}'  \
     'https://api.capgun.io/v1/orders/estimate.json'
```

```json
{
  "order": {
    "url": "http://rubygems.org/",
    "notify": null,
    "cost": 1,
    "viewport": "1024x768",
    "images": {
      "xlarge": "640x480"
    },
    "packages": [
      "base"
    ],
    "options": [
      {
        "package": "base"
      },
      {
        "url": "http://rubygems.org/"
      },
      {
        "notify": null
      },
      {
        "timeout": 5000
      },
      {
        "viewport": "1024x768"
      },
      {
        "image": {
          "xlarge": "640x480"
        }
      }
    ]
  }
}
```


## capture

Capture executes an order.  The order object lists the assets that will be
delivered in the order, the order's cost, and the job representing the order.

```ruby
# returns a Capgun::Order object
order = Capgun.capture("http://www.google.com/")
# attributes: id, url, notify, cost, viewport, packages, images, asset_urls, options, job
order.viewport
```

example JSON responses from the capgun service.

```shell
curl -H 'Authorization: abc123' \
     --data '{"url":"http://rubygems.org/"}'  \
     'https://api.capgun.io/v1/orders.json'
```

```json
{
  "order": {
    "created_at": "2013-04-17T20:23:29-07:00",
    "url": "http://rubygems.org/",
    "notify": null,
    "cost": 1,
    "viewport": "1024x768",
    "images": {
      "xlarge": "640x480"
    },
    "packages": [
      "base"
    ],
    "id": "u1qj2mz1",
    "options": [
      {
        "package": "base"
      },
      {
        "url": "http://rubygems.org/"
      },
      {
        "notify": null
      },
      {
        "timeout": 5000
      },
      {
        "viewport": "1024x768"
      },
      {
        "image": {
          "xlarge": "640x480"
        }
      }
    ],
    "job": {
      "state": "initialized",
      "transition": "capturing",
      "id": "qy9ujcly"
    }
  }
}
```


## status

Status is a lighter call to get the status of an order.

```ruby
# returns a Capgun::Job object
job = Capgun.status("qy9ujcly")
# attributes: id, state, order_id
job.state
```

example JSON responses from the capgun service.

```shell
curl -H 'Authorization: abc123' 'https://api.capgun.io/v1/jobs/qy9ujcly'
```

```json
{
  "job": {
    "state": "initialized",
    "transition": "capturing",
    "created_at": "2013-04-17T20:23:29-07:00",
    "id": "qy9ujcly",
    "order_id": "u1qj2mz1"
  }
}
```


## order

Fetches an existing order object and lists the assets that it delivers in the
order, the order's cost, and the job representing the order.

```ruby
# returns a Capgun::Order object
order = Capgun.order("u9qj2mc9")
# attributes: url, notify, cost, viewport, packages, images, options
order.asset_urls
order.asset_urls["xlarge"]
order.asset_urls["package"]
```

example JSON responses from the capgun service.

```shell
curl -H 'Authorization: abc123' 'https://api.capgun.io/v1/orders/u9qj2mc9'
```

```json
{
  "order": {
    "created_at": "2013-02-17T22:45:20-08:00",
    "url": "http://rubygems.org/",
    "notify": null,
    "cost": 1,
    "viewport": "1024x768",
    "images": {
      "xlarge": "640x480"
    },
    "asset_urls": {
      "xlarge": "https://api.capgun.io/v1/orders/u9qj2mc9/640x480.png",
      "package": "https://api.capgun.io/v1/orders/u9qj2mc9/package.zip"
    },
    "packages": [
      "base"
    ],
    "id": "u9qj2mc9",
    "options": [
      {
        "package": "base"
      },
      {
        "url": "http://rubygems.org/"
      },
      {
        "notify": null
      },
      {
        "timeout": 5000
      },
      {
        "viewport": "1024x768"
      },
      {
        "image": {
          "xlarge": "640x480"
        }
      }
    ],
    "job": {
      "state": "completed",
      "transition": "complete",
      "queued": 1.2787141799926758,
      "capturing": 25.210319995880127,
      "processing": 4.529249906539917,
      "duration": 31.01828408241272,
      "id": "5dlj5i1u"
    }
  }
}
```