lucid_shopify

Installation

Add the gem to your ‘Gemfile’:

gem 'lucid_shopify'

Usage

Configure the default API client

LucidShopify.configure(
  api_key: '...',
  api_version: '...', # e.g. '2019-07'
  billing_callback_uri: '...',
  callback_uri: '...', # (for OAuth; unused by this gem)
  logger: Logger.new(STDOUT),
  scope: '...',
  shared_secret: '...',
  webhook_uri: '...',
)

Alternatively load the configuration from a Ruby file. The Ruby file is evaluated and should return a hash.

LucidShopify.configure_from_file('config/shopify.rb') # the default path

When loading from a file, any environment variables matching the upcased key with the prefix ‘SHOPIFY_’ will override values in the file. For example ‘SHOPIFY_SHARED_SECRET=...’.

All keys are optional and in some private apps, you may not require any configuration at all.

Additionally, each API request requires authorisation:

credentials = LucidShopify::Credentials.new(
  '...', # myshopify_domain
  '...', # access_token
)

If the access token is omitted, the request will be unauthorised. This is only useful during the OAuth2 process.

Configure webhooks

Configure each webhook the app will create (if any):

webhooks = LucidShopify::Container['webhook_list']

webhooks.register('orders/create', fields: 'id,tags'}

Register webhook handlers

For each webhook, register one or more handlers:

handlers = LucidShopify::Container['webhook_handler_list']

handlers.register('orders/create', OrdersCreateWebhook.new)

See the inline method documentation for more detail.

To call/delegate a webhook to its handler for processing, you will likely want to create a worker around something like this:

webhook = LucidShopify::Webhook.new(myshopify_domain, topic, data)

handlers.delegate(webhook)

Create and delete webhooks

Create/delete all configured webhooks (see above):

LucidShopify::CreateAllWebhooks.new.(credentials)
LucidShopify::DeleteAllWebhooks.new.(credentials)

Create/delete webhooks manually:

webhook = {topic: 'orders/create', fields: %w(id tags)}

LucidShopify::CreateWebhook.new.(credentials, webhook)
LucidShopify::DeleteWebhook.new.(credentials, webhook_id)

Verification

Verify callback requests with the request params:

begin
  LucidShopify::VerifyCallback.new.(params)
rescue LucidShopify::Error => e
  # ...
end

Verify webhook requests with the request data and the HMAC header:

begin
  LucidShopify::VerifyWebhook.new.(data, hmac)
rescue LucidShopify::Error => e
  # ...
end

Authorisation

authorise = LucidShopify::Authorise.new

access_token = authorise.(credentials, authorisation_code)

Billing

Create a new charge:

create_charge = LucidShopify::CreateCharge.new

charge = create_charge.(credentials, charge) # see LucidShopify::Charge

Redirect the user to charge['confirmation_url']. When the user returns (see config.billing_callback_uri), activate the accepted charge:

activate_charge = LucidShopify::ActivateCharge.new

activate_charge.(credentials, accepted_charge)

Make API requests

client = LucidShopify::Client.new

client.get(credentials, 'orders', since_id: since_id)['orders']
client.post_json(credentials, 'orders', new_order)

Request logging is disabled by default. To enable it:

LucidShopify.configure(
  logger: Logger.new(STDOUT),
)

Make throttled API requests

client.throttled.get(credentials, 'orders')
client.throttled.post_json(credentials, 'orders', new_order)

Note that throttling currently uses a naive implementation that is only maintained across a single thread.