Megar <img src=“https://secure.travis-ci.org/tardate/megar.png” />

Megar (“megaargh!” in pirate-speak) is a Ruby wrapper and command-line (CLI) client for the Mega API.

It needs a few more API functions implemented to make it halfway useful, but it’s a start. You can connect and get file/folder listings at the moment.

Requirements and Known Limitations

Consider this totally alpha at this point, especially since the Mega API has yet to be formally and fully documented.

Currently tested with MRI 1.9.3
MRI 1.9.2 and 2.x not yet tested
Rubinius and JRuby 1.9 modes not yet tested
No plans to support 1.8 Ruby branches

Mega API coverage is far from complete at this point (help appreciated!). Here’s the run-down:

Supported API functions:

User/session management: Complete accounts
Login session challenge/response
Retrieve file and folder nodes

Currently unsupported API functions:

User/session management: Ephemeral accounts
User/session management: Confirming accounts
Retrieve user nodes
Add/copy nodes
Delete node
Move node
Set node attributes
Create/delete public handle
Create/modify/delete outgoing share
Key handling - Set or request share/node keys
Request download URL
Request upload URL
Add/update user
Get user
Retrieve user’s public key
Add/update/delete contact
Invite user
Send confirmation e-mail
Obtain user details by invitation code
Verify e-mailed confirmation code
List user sessions
User quota details
… and any other API features not explicitly listed above

The Megar Cookbook

How do I install it for normal use?

Add this line to your application’s Gemfile:

gem 'megar'

And then execute:

$ bundle

Or install it yourself as:

$ gem install megar

How to start an authenticated session

The Megar::Session object is the main entry point for the library. All requests on the Mega API are made in the context of an established session.

# create a session with immediate authentication
session = Megar::Session.new(email: '[email protected]', password: 'my_password')

It’s possible to delay the authentication

# create a session with deferred authentication
session = Megar::Session.new(email: '[email protected]', password: 'my_password', autoconnect: false )
# then explicitly login:
session.connect!

How to get a listing of all folders

Folders are accessed through an authenticated Megar::Session object.

all_folders = session.folders

folders is an enumerable collection, so you can iterate as you would expect:

session.folders.each do |folder|
  puts folder.name
end

How to get a handle to the special Mega folders

In addition to any folders you create yourself, Mega provides three standard folders: root (“Cloud Drive”), inbox and trash. Shortcuts are available on the folders collection to grab a handle on these directly:

my_folders = session.folders
my_folders.root
my_folders.inbox
my_folders.trash

What are all the attributes of a folder?

Once you have a folder object (e.g. session.folders.first), the following are the primary attributes it exposes:

id: the unique ID, corresponds to the Mega node handle
name: the name of the folder

How to get a listing of all files in a folder

A folder node provides a files collection

session.folders.first.files.each do |file|
  puts file.name
end

How to get a listing of all files

All files can be accessed directly without needing to navigate via a folder object.

all_files = session.files

files is an enumerable collection, so you can iterate as you would expect:

session.files.each do |file|
  puts file.id
  puts file.name
  puts file.size
end

What are all the attributes of a file?

Once you have a file object (e.g. session.files.first), the following are the primary attributes it exposes:

id: the unique ID, corresponds to the Mega node handle
name: the name of the file
size: the size of the file content (in bytes)

CLI: How to use the command-line client

The gem installation includes a command-line tool. Call it without parameters and it will show help:

$ megar

All operations require credentials to ba passed on the command line (email and password arguments):

$ megar [email protected] --password=mypassword
Connecting to mega as [email protected]..
Connected!

CLI: How to get a file listing

Use the ls command:

$ megar [email protected] --password=mypassword ls
Connecting to mega as [email protected]..
              39 bytes  74ZTXbyR    hello_mega.txt
          137080 bytes  L0xHwayA    mega.png

How to run tests

Test are implemented using rspec. Run tests with rake or rake spec.

Guard is installed as part of the development dependencies, so to start continuous test execution on file change, start it up with bundle exec guard.

How to refresh unit test expectations

Unit tests make liberal use of expected responses from the actual Mega API. In order to enable good unit tests without hitting the Mega API for real, test expectations are stored as JSON under ‘spec/fixtures/crypto_expectations’.

A rake task is available to re-generate the expectations:

$ rake gen:crypto_expectations [email protected] password=mypassword

Generating crypto_expectations for [email protected]...

Done! New crypto_expectations for unit test written to:
/.../megar/spec/fixtures/crypto_expectations/sample_user.json

NOTE: the email and password are stored in the expectations file, so be careful not to commit and distribute credentials. Change the password on the account first. The tests will still run as intended with the snapshot of crypto details stored in the expectations file.

References

Contributing

Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so it doesn’t get broken in a future version unintentionally.
Please try not to mess with the gemspec, Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so it can be cherry-picked around.