The Spackle Ruby library provides optimized access to billing aware flags created on the Spackle platform.

See the Ruby API docs.

gem install spackle-ruby

source 'https://rubygems.org'

gem 'spackle-ruby'

In order to use Spackle, you need to configure your secret key on the Spackle module. You can find your secret key in Spackle app settings page.

require 'spackle'

Spackle.api_key = "<api key>"

pricing_table = Spackle::PricingTable.retrieve("abcde123")

{
  id: string
  name: string
  intervals: string[]
  products: {
    id: string
    name: string
    description: string
    features: {
      id: string
      name: string
      key: string
      type: number
      value_flag: boolean
      value_limit: number | null
    }[]
    prices: {
      month?: {
        id: string
        unit_amount: number
        currency: string
      }
      year?: {
        id: string
        unit_amount: number
        currency: string
      }
    }
  }[]
}

Spackle uses stripe ids as references to customer features.

customer = Spackle::Customer.retrieve("cus_00000000")

customer.enabled("feature_key")

customer.limit("feature_key")

A customer's current subscriptions are available on the subscriptions property. These are valid Stripe::Subscription objects as defined in the Stripe Ruby library.

customer.subscriptions

There is a brief delay between when an action takes place in Stripe and when it is reflected in Spackle. To account for this, Spackle provides a Waiters module that can be used to wait for a Stripe object to be updated and replicated.

1. Wait for a customer to be created

   Spackle::Waiters.wait_for_customer("cus_00000000")

2. Wait for a subscription to be created

   Spackle::Waiters.wait_for_subscription("cus_000000000", "sub_00000000")

3. Wait for a subscription to be updated

   Spackle::Waiters.wait_for_subscription("cus_000000000", "sub_00000000", status: "active")

These will block until Spackle is updated with the latest information from Stripe or until a timeout occurs.

In production, Spackle requires a valid Stripe customer. However, that is not development environments where state needs to be controlled. As an alternative, you can use a file store to test your application with seed data.

/app/spackle.json

{
  "cus_000000000": {
    "features": [
      {
        "type": 0,
        "key": "flag_feature",
        "value_flag": true
      },
      {
        "type": 1,
        "key": "limit_feature",
        "value_limit": 100
      }
    ],
    "subscriptions": [
      {
        "id": "sub_000000000",
        "status": "trialing",
        "quantity": 1
      }
    ]
  }
}

Then configure the file store in your application:

Spackle.store = Spackle::FileStore.new('/app/spackle.json')

In production, Spackle requires a valid Stripe customer. However, that is not ideal in testing or some development environments. As an alternative, you can use an in-memory store to test your application with seed data.

Spackle.store = Spackle::MemoryStore.new()
Spackle.store.set_customer_data("cus_000000000", {
  "features": [
    {
      "type": 0,
      "key": "flag_feature",
      "value_flag": True,
    },
    {
      "type": 1,
      "key": "limit_feature",
      "value_limit": 100,
    },
  ],
  "subscriptions": [
     {
       "id": "sub_000000000",
       "status": "trialing",
       "quantity": 1,
     }
  ]
})

Note: The in-memory store is not thread-safe and state will reset on each application restart.

The Spackle Ruby library emits logs as it performs various internal tasks. You can control the verbosity of Spackle's logging a few different ways:

1. Set the environment variable SPACKLE_LOG to the value debug, info, warn or error

   $ export SPACKLE_LOG=debug

2. Set Spackle.log_level:

   Spackle.log_level = 'debug'