gumroad_elixir

Hex.pmHex Docs.github/workflows/ci.yml

An unofficial Gumroad API client for Elixir applications.

⚠️ Pay heed! This package does not yet implement the complete Gumroad API. See the "Incomplete implementation" section below for more details.

Documentation

Full documentation available on HexDocs.

Usage

iex> {:ok, products} = Gumroad.get_products()
iex> products
[%Gumroad.Product{id: "...", name: "..."}, %Gumroad.Product{id: "...", name: "..."}]

iex> {:ok, subscribers} = Gumroad.get_subscribers(List.first(products).id)
[%Gumroad.Subscriber{id: "...", status: "alive"}]

Installation

Add gumroad_elixir to your list of dependencies in mix.exs:

def deps do
  [
    {:gumroad_elixir, "~> 0.1.0"}
  ]
end

Configuration

Configuration properties on the :gumroad_elixir application are:

Error handling

Error messages sent by Gumroad's API in response to failed requests are propagated as-is to your application:

iex> Gumroad.get_sale("not-a-real-sale")
{:error, "The sale was not found."}

Authentication

Authentication is handled per Gumroad's API docs. An access token is included as a parameter on each request made to the Gumroad API.

To create an access token, see Gumroad's docs.

Testing

Gumroad doesn't currently offer a native solution for local development or testing. To make up for this, this package includes local dev and testing mocks which ensure that you don't have to make calls to the live Gumroad API from non-prod environments.

To use mock responses, configure :gumroad_elixir:client to Gumroad.Client.Mock (more details on the Gumroad.Client docs).

Now when you perform an action that would create a request against the Gumroad API, you'll get a mocked response instead without having to contact the Gumroad API:

iex> Gumroad.get_resource_subscriptions("abc")
{:ok,
 %Gumroad.ResourceSubscription{
   id: "test-resource-subscription-id",
   post_url: "http://example.org",
   resource_name: "abc"
 }}

Incomplete implementation

This package does not implement the entire Gumroad API. I extracted it out of a project (Mailgrip) where I only implemented support for the endpoints I needed.

An overall framework has been created though, with the intention of making addition of new endpoints straightforward.

If you'd like support for a new endpoint, I'd love for you to open a PR (my preference!) or otherwise open an issue and I can look into adding support.

What API endpoints are implemented?

The following table tracks all endpoints currently available on the Gumroad API and whether they've been implemented in this package.

Gumroad API Implemented?
GET /products ✅
GET /products/:product_id/subscribers ✅
PUT /resource_subscriptions ✅
GET /resource_subscriptions ✅
DELETE /resource_subscriptions/:resource_subscription_id ✅
GET /sales/:id ✅
GET /subscribers/:id ✅
GET /sales ✅
GET /products/:id ❌
DELETE /products/:id ❌
PUT /products/:id/enable ❌
PUT /products/:id/disable ❌
POST /products/:product_id/variant_categories ❌
GET /products/:product_id/variant_categories/:id ❌
PUT /products/:product_id/variant_categories/:id ❌
DELETE /products/:product_id/variant_categories/:id ❌
GET /products/:product_id/variant_categories ❌
POST /products/:product_id/variant_categories/:variant_category_id/variants ❌
GET /products/:product_id/variant_categories/:variant_category_id/variants/:id ❌
PUT /products/:product_id/variant_categories/:variant_category_id/variants/:id ❌
DELETE /products/:product_id/variant_categories/:variant_category_id/variants/:id ❌
GET /products/:product_id/variant_categories/:variant_category_id/variants ❌
GET /products/:product_id/offer_codes ❌
GET /products/:product_id/offer_codes/:id ❌
POST /products/:product_id/offer_codes ❌
PUT /products/:product_id/offer_codes/:id ❌
DELETE /products/:product_id/offer_codes/:id ❌
GET /products/:product_id/custom_fields ❌
POST /products/:product_id/custom_fields ❌
PUT /products/:product_id/custom_fields/:name ❌
DELETE /products/:product_id/custom_fields/:name ❌
GET /user ❌
PUT /sales/:id/mark_as_shipped ❌
PUT /sales/:id/refund ❌
POST /licenses/verify ❌
PUT /licenses/enable ❌
PUT /licenses/disable ❌
PUT /licenses/decrement_uses_count ❌

What else needs to be done?

Besides supporting all API endpoints, there are a few other areas I'd like to tackle before calling this client "production ready":