# Refcode

Currently a standalone gem for converting arbitrary Ruby objects into encrypted,
URL-safe strings. The strings can be simply decrypted later to be used by your
application.

Refcode was conceived as a way to attach referral data to tracking links. Encryption
makes it unlikely that the links will be tampered with. Still, it is not recommended
for critically sensitive applications! It was designed to power a simple referral
link tracking system.

## Implementation

- **Encryption** using the AES-256-CBC algorithm with https://github.com/attr-encrypted/encryptor which wraps the Ruby OpenSSL library.

- **Base64 encoding** is handled by https://github.com/nojima/base64url which implements a slight tweak to the standard Base64 algorithm to create URL-safe strings.

- **Serialization** with YAML.

## Installation

Add this line to your application's Gemfile:

    gem 'refcode'

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install refcode

## Usage

Refcode can be used in two ways. Most simply, you can use the `Refcode::Encoder` class directly.

    encoder = Refcode::Encoder.new do |e|
      e.secret = "a long crunchy secret"
      e.salt = "some salt"
    end

    something = OpenStruct.new(channel: 'facebook', action: 'message', user_id: 43765)
    encoded_param = encoder.encode something

    # in some future request:

    something = encoder.decode params[:encoded_param]
    puts something.channel # 'facebook'

For added convenience when using Refcode with an ORM such as ActiveRecord, a module called `Refcode::Encodable` is also provided.

    class Job < ActiveRecord::Base
      include Refcode::Encodable
      has_refcode secret: 'a long crunchy secret', salt: :id
    end

    # the salt option of the has_refcode method can accept a proc/lambda, string
    # or a symbol representing an existing method on the class (id in this case)

    # in some controller code:

    @job = Job.find params[:id]
    referral_code = @job.generate_refcode channel: 'facebook', action: 'message', user_id: 43765

    # and in another action:

    @job = Job.find params[:id]
    referral_data = @job.parse_refcode params[:encoded_param]


## Contributing

1. Fork it
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 new Pull Request