Stackd Ruby Client

Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file lib/stackd. To experiment with that code, run bin/console for an interactive prompt.

TODO: Delete this and the text above, and describe your gem

Installation

Add this line to your application's Gemfile:

gem 'stackd'

And then execute:

$ bundle

Or install it yourself as:

$ gem install stackd

Usage

Creating a client

$stackd = Stackd::Client.new id: 'YOUR_CLIENT_ID',
                             secret: 'YOUR_CLIENT_SECRET'

Getting an app token

app_token = $stackd.auth_requests.client scope: 'a,b,c'
# => <Stackd::Token app_id: "YOUR_CLIENT_ID",
#                   scope: "a,b,c",
#                   access_token: "e1979b29529ac",
#                   expires_in: 3600>

Getting a user token

class MyController
  def authorize
    auth_request = $stackd.auth_requests.new redirect_uri: 'YOUR_CALLBACK_URL',
                                             scope: 'a,b,c'

    session[:auth_state] = auth_request.state

    redirect_to auth_request.url
    # stackd.com/authorize?client_id=...&state=...&redirect_uri=...&scope=...
  end

  def callback
    auth_request = $stackd.auth_requests.new state: session[:state]

    user_token = auth_request.callback code: params[:code],
                                       state: params[:state]
    # => <Stackd::Token user_id: "09545bce-3c31-4593-99bd-1dfe8b98df93",
    #                   scope: "a,b",
    #                   access_token: "e1979b29529ac",
    #                   refresh_token: "ca92592b9791e",
    #                   expires_in: 3600>
  end
end

Refreshing a user token

refreshed_user_token = $stackd.auth_requests.refresh user_token

Persisting tokens (example)

rails generate model TokenData \
  user_id:string \
  scope:string \
  access_token:string \
  refresh_token:string \
  expires_in:integer

Stackd::Token.on_grant do |token|
  TokenData.create! user_id: token.user_id,
                    scope: token.scope,
                    access_token: token.access_token,
                    refresh_token: token.refresh_token,
                    expires_in: token.expires_in
end

class TokenData
  def self.fresh_token_by criteria
    # ...
    token = $stackd.tokens.new user_id: user_id,
                               scope: scope,
                               access_token: access_token,
                               refresh_token: refresh_token,
                               expires_in: expires_in,
                               token_type: 'bearer'

    if expired?
      $stackd.auth_requests.refresh token
    else
      token
    end
  end

  def expired?
    Time.now > created_at + expires_in.seconds
  end
end

Making requests

https://stackd.com/docs

token.post :rappers, name: 'Marshall Mathers'
# POST /rappers
# {"name": "Marshall Mathers"}
# => { ... }

token.patch :rappers, ':id', name: 'EMIN3M'
# PATCH /rappers/:id
# {"name": "EMIN3M"}
# => { ... }

token.get :rapper, ':id'
# GET /rappers/:id
# => { ... }

token.get :rappers, q: 'Slim Shady'
# GET /rappers?q=Slim%20Shady
# => { rappers: [ ... ], ... }

token.get '/any/url'
# GET /any/url

Application errors (4xx)

Will throw a Stackd::Error:

# <Stackd::Error error="error_code"
#                error_description="Something went wrong."
#                error_uri="https://stackd.com/docs/errors#error_code">

Server errors (5xx)

Will throw a Stackd::ServerError.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment. Run bundle exec stackd to use the code located in this directory, ignoring other installed copies of this gem.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release to create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

1. Fork it ( https://github.com/stackd/stackd-ruby/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