KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

betsy

★ 10 Open GitHub ↗

A better Ruby on Rails Etsy gem!

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![RubyGem](https://img.shields.io/gem/v/betsy.svg)](https://rubygems.org/gems/betsy)
[![Build Status](https://app.travis-ci.com/JaceBayless/betsy.svg?branch=main)](https://app.travis-ci.com/JaceBayless/betsy)
[![Coverage Status](https://coveralls.io/repos/github/JaceBayless/betsy/badge.svg?branch=main)](https://coveralls.io/github/JaceBayless/betsy?branch=main)
[![Maintainability](https://api.codeclimate.com/v1/badges/11674e695f86e7507fb9/maintainability)](https://codeclimate.com/github/JaceBayless/betsy/maintainability)

# Betsy

Betsy is an unopinionated gem for using the Etsy API. Betsy is designed to be a 1-to-1 mapping of Etsy's API giving you access to all endpoints and all available data.

## Installation

First, install Betsy by adding it to your gemfile:

```ruby
gem 'betsy'
```

And then run:

$ bundle install

Next, you need to run the generator:

$ rails generate betsy:install

Running the generator will create an `etsy_account` model in your app as well as a migration for this model. The purpose of this model is to allow you to easily link and store an Etsy account. This model is used within the gem by providing the `access_token` and `refresh_token` needed with making calls that require authentication. You can add anything to this model as long as the original fields are left as-is. This may be useful if you wish your application to have relations with an Etsy account.

Finally, you need to run the migration:

$ rails db:migrate

## Usage

After running the generator and migrating, open config/initializers/betsy.rb and set your API key and redirect url to the correct values.

Now Betsy should be configured for use.

### Getting Authenticated
To begin going through the authentication process you will first start by using Betsy to generate an authorization URL:

```ruby
Betsy.authorization_url
```

By default `authorization_url` requests access for all scopes, if you would prefer more restrictive scopes can also be passed to `authorization_url` like so:

```ruby
Betsy.authorization_url(scope: ["address_r", "address_w"])
```

Going to the URL generated by `authorization_url` will ask the user to grant access to their account. Then they will be redirected back to your site. This will update the `EtsyAccount` with the `access_token` and `refresh_token`.

### Making Unauthenticated API Requests

Betsy is made to mimic [Etsy's API](https://developers.etsy.com/documentation/reference). To make a call you will use the Betsy class for that category, i.e. for `ShopListing Inventory` the class would be `Betsy::ShopListingInventory`. All the methods listed in the Etsy documentation are available to use by calling that method on the category class following proper Ruby syntax, i.e. `Betsy::ShopListingInventory.get_listing_inventory`. The only parameters for these methods are path parameters, such as `shop_id` or `listing_id` and these are passed in the order in which they appear in the URL. All other parameters can be passed as named parameters. Betsy handles your API key so this does not need to be passed to these methods.

### Making Authenticated API Requests

To make an API request that is authenticated follow the instructions above but also pass a named parameter `etsy_account` with an `EtsyAccount` model.

```ruby
Betsy::UserAddress.get_user_addresses(etsy_account: EtsyAccount.first)
```

### Refreshing Access Tokens

By default, Betsy handles the refreshing of authentication tokens for you.

## Migrating from v0.2.x to v0.3.x

### Account model requires `token_expired?`

In v0.3.0, the token expiration check was moved out of the gem and into your account model. You need to add a `token_expired?` method to your `EtsyAccount` model (or whatever model you configured via `Betsy.account_model`):

```ruby
class EtsyAccount < ApplicationRecord
  def token_expired?
    last_token_refresh.nil? || expires_in.nil? || last_token_refresh + expires_in <= DateTime.now
  end
end
```

This gives you full control over the expiration logic. For example, you could add a buffer to refresh tokens early:

```ruby
def token_expired?
  last_token_refresh.nil? || expires_in.nil? || last_token_refresh + expires_in - 5.minutes <= DateTime.now
end
```

### Faraday removed

Betsy no longer depends on Faraday. It uses Ruby's built-in `Net::HTTP` instead. If your app was relying on Betsy to pull in Faraday, you'll need to add it to your own Gemfile.

## License

The gem is available as open-source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## Contributing

If you would like to contribute to this gem feel free to open issues or fork this repository and open a pull request.

## Special thanks.

Thanks to [Will](https://github.com/willtcarey) and [Mark](https://github.com/markvanlan) for answering my endless supply of questions when creating this gem.

betsy

Was this content helpful?

Recent Feedback

Download README