Versacommerce::ThemeAPIClient

Versacommerce::ThemeAPIClient is a library to consume the VersaCommerce Theme API.

Ruby ≥ 3.1.0

Add this line to your application's Gemfile:

gem 'versacommerce-theme_api_client'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install versacommerce-theme_api_client

Create a client object to work on:

require 'versacommerce/theme_api_client'

authorization = 'YOUR_AUTHORIZATION'
client = Versacommerce::ThemeAPIClient.new(authorization: authorization)

The client object is tied to a single theme, depending on the authorization. You can get an authorization from your shop's admin section.

The client accepts the following configuration options:

client = Versacommerce::ThemeAPIClient.new(
  authorization: 'YOUR_AUTHORIZATION',  # Required: API authorization token
  base_url: 'https://theme-api.versacommerce.de',  # Optional: Custom API endpoint
  ssl_verify: true  # Optional: Enable/disable SSL certificate verification (default: true)
)

By default, SSL certificate verification is enabled. You can disable it for development/testing environments with self-signed certificates:

client = Versacommerce::ThemeAPIClient.new(
  authorization: 'YOUR_AUTHORIZATION',
  ssl_verify: false  # Disable SSL verification (not recommended for production)
)

Warning: Disabling SSL verification is not recommended for production environments.

If you need to connect to a different API endpoint (e.g., staging environment):

client = Versacommerce::ThemeAPIClient.new(
  authorization: 'YOUR_AUTHORIZATION',
  base_url: 'https://staging-theme-api.example.com'
)

Calling #directories on the client object will get you a DirectoryRelation object that responds to #each. As it includes the Enumerable module, the following will get you an array of all directories:

directories = client.directories.to_a

If you want to get an array of a directory's child directories, call:

directories = client.directories.in_path('path/to/directory').to_a

This is practically the same as calling:

directories = client.directories(path: 'path/to/directory')

These calls are recursive and will return all directory children by default. If you don't want this behaviour and instead only get direct child directories, turn it off by calling:

directories = client.directories(recursive: false)

# respectively:
directories = client.directories.in_path('', recursive: false)

If you want to find a single directory, call:

directory = client.directories.find('path/to/directory')

Nesting with the relation is also possible. The following will try to find the directory assets/font:

directory = client.directories(path: 'assets').find('font')

If the directory could be found, a Directory instance is returned, else a RecordNotFoundError is raised. A Directory instance has a path instance variable representing its path and responds to #files, which returns a FileRelation with the directory's path as base for the files.

In order to create a directory, use #build in combination with #save or use #create:

directory = client.directories.build(path: 'special_font')
directory.save # => true or false

# which is basically the same as:
directory = client.directories(path: 'assets/font').create(path: 'special_fonts')

If the directory could not be saved, false will be returned and the directory.errors object populated with the errors that occured.

Updating a directory is similar to creating one:

directory.update(path: 'new/path')

# which is basically the same as:
directory.path = 'new/path'
directory.save

Delete a directory by calling:

directory.delete

If you don't want to prefetch a directory in order to delete it, there's also:

client.directories.delete('path/to/directory')

Working with files is like dealing with directories. You can retrieve all files by calling:

files = client.files.to_a

This will return an array of all files. A significant difference between a directory and a file is that a file can have content. Finding files using the method described above won't load the files' contents though. Reloading the content is possible:

file = client.files.to_a.first
file.content # => nil

file.reload_content
file.content # => returns the content as String

Filtering files works like with a directory.

files = client.files(path: 'assets').to_a

# or
files = client.files.in_path('assets').to_a

will return all files in (or below) the assets directory.

file = client.files(path: 'assets').find('fonts/some_font.svg')

will find the file located at assets/fonts/some_font.svg. As this will be a text file, the content will be loaded automatically. If the file is an image (or any other file not in text format) the content will not be loaded. If you want to make sure the content is loaded, provide a load_content keyword argument:

file = client.files.find('assets/images/banner.png', load_content: true)

or load the content afterwards manually if it is missing:

file = client.files.find('assets/images/banner.png')
file.reload_content unless file.has_content?

In order to create a file, use #build in combination with #save or use #create:

file = client.directories.build(path: 'assets/fonts/some_font.svg', content: 'content here')
file.save # => true or false

# which is basically the same as:
file = client.directories.create(path: 'assets/font', content: 'content here')

If the file could not be saved, false will be returned and the file.errors object populated with the errors that occured.

Updating a file is similar to creating one:

file.update(path: 'new/path', content: 'new content')

# which is basically the same as:
file.path = 'new/path'
file.content = 'new content'
file.save

Delete a file by calling:

file.delete

If you don't want to prefetch a file in order to delete it, there's also:

client.files.delete('path/to/file')

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

1. Fork it (https://github.com/versacommerce/versacommerce-theme_api_client/fork)
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 a new Pull Request

MIT.