lightspeed_pos 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f479289d48eb83582ea0f30e93bf82644e0a5cad
-  data.tar.gz: a0b8758eaeeaa5f7f6f044cc9bdd3689156f6d03
+  metadata.gz: d3960f7c39629798ffae0406f84fb2cbcf897390
+  data.tar.gz: f900f23a42324bf61268b0ab4f43ac0528971c38
 SHA512:
-  metadata.gz: be2f7ba8a83b024b43def375f084ab63f695087651563e690f4ec235c453b1f19d54cf0e938f5fd31a04fb83e110d8c0fde4c5006bac7c405f6da6c987bc9891
-  data.tar.gz: e04d5d7c4dabf225688e79e5bf071cd86c371ec5dd2fffea4d88721970ceeb4558cf3b996a24b42ebaf3a3f9be15cd2d72ee3b5dec07011bfc38a4d37bbeaa41
+  metadata.gz: 7e7e1f10edaa984d5e232c9706f32e3b6d13bb8cae0cb3c5e00f773335493a3372085e7d85c7411ccb425f20fe8ab341d98075273d39f5e418d839b32cf99478
+  data.tar.gz: 856a6628c9c7c4dd36b10e25a253bc394230600e5632c3e961242a285e9154d34b99564fb063e06ebf376feb7ffd74ddd7397faaa9a2e20a08206f4e7a02e474

data/README.markdown

@@ -1,23 +1,13 @@
 # Lightspeed POS
 
-[![Build Status](https://travis-ci.org/radar/lightspeed-pos.svg?branch=master)](https://travis-ci.org/radar/lightspeed-pos)
-[![Code Climate](https://codeclimate.com/github/radar/lightspeed-pos/badges/gpa.svg)](https://codeclimate.com/github/radar/lightspeed-pos)
+An _unofficial_ gem for interacting with [Lightspeed's Point of Sale API](http://www.lightspeedpos.com/retail/help/developers/api/basics/), ([documentation](http://cloud-docs.lightspeedapp.com/API/APIHelp.help)).
 
-
-An _unofficial_ gem for interacting with [Lightspeed's Point of Sale API](http://www.lightspeedpos.com/retail/help/developers/api/basics/). Works with API keys for the time being.
-
-Most definitely not production ready yet, but you can help by submitting pull requests!
+Not all endpoints are implemented yet, but you can help by submitting pull requests!
 
 ## Getting Started
 
 First, intialize a new client:
 
-```ruby
-client = Lightspeed::Client.new(api_key: "YOUR_API_KEY_HERE")
-```
-
-**OR** you may also choose to pass through an OAuth access token if you have one:
-
 ```ruby
 client = Lightspeed::Client.new(oauth_token: "YOUR_ACCESS_TOKEN_HERE")
 ```
@@ -25,22 +15,33 @@ client = Lightspeed::Client.new(oauth_token: "YOUR_ACCESS_TOKEN_HERE")
 Next, make a request for your accounts:
 
 ```ruby
-accounts = client.accounts
+accounts = client.accounts.all
 ```
 
 Pick the account you want to use, and then start using it:
 
 ```ruby
 account = accounts.first
-account.items # This will return the first 100 items from the account
+account.items.first
 ```
 
-## Account Resources
+## Resources
 
-Account resources share a common API. Account resources that are currently supported by this library are:
+resources share a common API. Resources that are currently supported by this library are:
 
+* Accounts
 * Categories
+* Employees
 * Items
+* Item Matrices
+* Item Attribute Sets
+* Images
+* Inventories
+* Orders
+* Sales
+* Shops
+* Special Orders
+* Vendors
 
 To work with account resources, you first need to fetch an account. The examples below are for items, but will also work with other types listed above.
 
@@ -52,6 +53,28 @@ You can fetch a list of items with this:
 account.items.all
 ```
 
+You can pass query parameters to this by using the `params` keyword:
+
+```ruby
+account.items.all(params: { itemMatrixID: 0 })
+```
+
+You can enumerate over a group of 100 resources at a time (the max in a single request) using `each_page`
+
+```ruby
+account.items.each_page! do |items|
+  # ItemImporter.import(items)
+end
+```
+
+Or enumerate over each resource using #each (this still only does a request for each 100 items)
+
+```ruby
+account.items.each do |item|
+  # ItemImporter.import(item)
+end
+```
+
 ### Show
 
 You can fetch a particular item by its ID by doing this:
@@ -59,15 +82,19 @@ You can fetch a particular item by its ID by doing this:
 ```ruby
 account.items.find(1)
 ```
+If item with id of `1` is not there, this will raise `Lightspeed::Error::NotFound`
+
+You can fetch the first item using `first`
+```ruby
+account.items.first
+```
 
 ### Create
 
 You can create a particular item by calling `create`:
 
 ```ruby
-account.items.create({
-  description: "Onesie"
-})
+account.items.create(description: "Onesie")
 ```
 
 ### Update
@@ -75,24 +102,25 @@ account.items.create({
 You can update a particular item by calling `update`, passing that item's ID and providing a list of attributes to update:
 
 ```ruby
-account.items.update(1, {
-  description: "Onesie"
-})
+account.items.update(1, description: "Onesie")
+# OR
+account.items.find(1)
+item.update(description: "Onesie")
 ```
 
-This method isn't available on items themselves because I couldn't work out how to share the account ID easily there.
-
 ### Destroy
 
 You can destroy a particular item by calling `destroy` and passing that item's ID:
 
 ```ruby
-account.items.destroy(1)
+account.images.destroy(1)
+# OR
+account.images.find(1)
+item.destroy
 ```
 
-For the `Items` resource, this is aliased to `archive`:
+For the `Item` resource, `destroy` is aliased to `archive`:
 
-```ruby
-account.items.archive(1)
-```
+## Rate Limiting
 
+This gem respects the `X-LS-API-Bucket-Level` header by pausing before a request that would otherwise overrun the API rate limit. It calls `Kernel.sleep` with the minimum number of seconds needed to avoid hitting the limit, which suspends the current thread during that time. If you need to make API calls across multiple Lightspeed accounts using this gem, its recommended to make requests against each account in a separate thread.

data/bin/console

@@ -1,14 +1,22 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "lightspeed/pos"
+require 'bundler/setup'
+require 'dotenv'
+require 'lightspeed_pos'
+Lightspeed::Request.verbose = true
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
 # require "pry"
 # Pry.start
+Dotenv.load
+def client
+  token = ENV['LIGHTSPEED_OAUTH_TOKEN']
+  raise 'set LIGHTSPEED_OAUTH_TOKEN as an envorinment variable to use this' unless token
+  @client ||= Lightspeed::Client.new(oauth_token: token)
+end
+
+def account
+  client.accounts.first
+end
 
-require "irb"
+require 'irb'
 IRB.start

data/lib/lightspeed/account.rb

@@ -1,48 +1,49 @@
-require 'lightspeed/base'
-require 'lightspeed/categories'
-require 'lightspeed/items'
-require 'lightspeed/item_matrices'
+require 'uri'
+require_relative 'categories'
+require_relative 'employees'
+require_relative 'items'
+require_relative 'item_matrices'
+require_relative 'item_attribute_sets'
+require_relative 'images'
+require_relative 'inventories'
+require_relative 'orders'
+require_relative 'sales'
+require_relative 'shops'
+require_relative 'special_orders'
+require_relative 'vendors'
 
 module Lightspeed
-  class Account < Lightspeed::Base
-    attr_accessor :id, :name, :link
-
-    def client
-      owner
-    end
-
-    def items
-      item_proxy
-    end
-
-    def categories
-      category_proxy
-    end
-
-    def item_matrices
-      item_matrices_proxy
-    end
-
-    def instantiate(*args)
-      client.instantiate(self, *args)
-    end
-
-    private
-
-    def self.id_field
-      "accountID"
-    end
-
-    def item_proxy
-      @item_proxy ||= Lightspeed::Items.new(self)
-    end
-
-    def category_proxy
-      @category_proxy ||= Lightspeed::Categories.new(self)
-    end
-
-    def item_matrices_proxy
-      @item_matrices_proxy ||= Lightspeed::ItemMatrices.new(self)
+  class Account < Lightspeed::Resource
+    fields(
+      accountID: :id,
+      name: :string,
+      link: :hash
+    )
+    relationships(
+      :Categories,
+      :Employees,
+      :Images,
+      :Inventories,
+      :ItemMatrices,
+      :ItemAttributeSets,
+      :Items,
+      :Orders,
+      :Sales,
+      :Shops,
+      :SpecialOrders,
+      :Vendors
+    )
+
+    def account
+      self
+    end
+
+    def link
+      if @link.is_a?(Hash)
+        @link['@attributes']['href']
+      else
+        @link
+      end
     end
   end
 end

data/lib/lightspeed/accounts.rb

@@ -0,0 +1,22 @@
+require_relative 'collection'
+require_relative 'account'
+
+module Lightspeed
+  class Accounts < Lightspeed::Collection
+    def base_path
+      '/Account'
+    end
+
+    def account
+      first_loaded || first
+    end
+
+    def page(n, *args)
+      # turns out lightspeed doesn't respect pagination for accounts.
+      # so page(1) is identical to page(0).
+      # they should be different, thus.
+      # if someone has more than 100 store accounts, well, good for them.
+      n.zero? ? super : []
+    end
+  end
+end

data/lib/lightspeed/categories.rb

@@ -1,10 +1,10 @@
-require 'lightspeed/category'
-require 'lightspeed/account_resources'
+require_relative 'category'
+require_relative 'collection'
 
 module Lightspeed
-  class Categories < Lightspeed::AccountResources
-    def self.resource_name
-      "Category"
+  class Categories < Lightspeed::Collection
+    def load_relations_default
+      nil
     end
   end
 end

data/lib/lightspeed/category.rb

@@ -1,10 +1,19 @@
-module Lightspeed
-  class Category < Base
-    attr_accessor :name, :nodeDepth, :fullPathName, :leftNode, :rightNode, :timeStamp, :parentID,
-      :createTime
+require_relative 'resource'
 
-    def self.id_field
-      "categoryID"
-    end
+module Lightspeed
+  class Category < Lightspeed::Resource
+    fields(
+      categoryID: :id,
+      name: :string,
+      nodeDepth: :integer,
+      fullPathName: :string,
+      leftNode: :integer,
+      rightNode: :integer,
+      createTime: :datetime,
+      timeStamp: :datetime,
+      parentID: :id,
+      Category: :hash
+    )
+    relationships Parent: :Category
   end
 end

data/lib/lightspeed/client.rb

@@ -1,45 +1,56 @@
-require 'lightspeed/account'
-require 'lightspeed/request'
+require 'active_support/core_ext/array/wrap'
+
+require_relative 'accounts'
+require_relative 'request'
+require_relative 'request_throttler'
 
 module Lightspeed
   class Client
-    attr_accessor :api_key, :oauth_token
+    attr_accessor :oauth_token, :throttler
 
-    def initialize(api_key: nil, oauth_token: nil)
-      @api_key = api_key
+    def initialize(oauth_token: nil)
       @oauth_token = oauth_token
-    end
-
-    def request(**args)
-      Lightspeed::Request.new(self, **args)
+      @throttler = Lightspeed::RequestThrottler.new
     end
 
     # Returns a list of accounts that you have access to.
     def accounts
-      request = request(method: :get, path: "/Account.json")
-      response = request.perform
-      instantiate(response["Account"], Lightspeed::Account)
+      @accounts ||= Lightspeed::Accounts.new(context: self)
     end
 
-    # Instantiates a bunch of records from Lightspeed into their proper classes.
-    def instantiate(owner = self, records, klass)
-      records = splat(records)
-      records.map do |record|
-        klass.new(owner, record)
+    def load_json(json)
+      data = JSON.parse(json)
+      Array.wrap(data).map do |resource|
+        resource = resource_class.new(context: self, attributes: resource)
+        @resources[resource.id] = resource
       end
     end
 
+    def get(**args)
+      perform_request(args.merge(method: :get))
+    end
+
+    def post(**args)
+      perform_request(args.merge(method: :post))
+    end
+
+    def put(**args)
+      perform_request(args.merge(method: :put))
+    end
+
+    def delete(**args)
+      perform_request(args.merge(method: :delete))
+    end
+
     private
 
-    # Converts a thing to an Array unless it is already.
-    # Unfortunately necessary because Lightspeed's API may return an object,
-    # or an array of objects.
-    #
-    # The compact is becuase it may return nothing at all.
-    # In the example of fetching categories resource where there are no categories,
-    # response["Category"] will not be present.
-    def splat(thing)
-      (thing.is_a?(Array) ? thing : [thing]).compact
+    def perform_request(**args)
+      @throttler.perform_request request(**args)
     end
+
+    def request **args
+      Lightspeed::Request.new(self, **args)
+    end
+
   end
 end

data/lib/lightspeed/collection.rb

@@ -0,0 +1,218 @@
+require 'active_support/core_ext/string'
+require 'active_support/core_ext/array/wrap'
+require 'active_support/json'
+require 'active_support/core_ext/object/json'
+
+module Lightspeed
+  class Collection
+    PER_PAGE = 100 # the max page of records returned in a request
+
+    attr_accessor :context, :resources
+
+    def initialize(context:, attributes: nil)
+      self.context = context
+      instantiate(attributes)
+    end
+
+    def account
+      context.account
+    end
+
+    def unload
+      @resources = {}
+    end
+
+    def load_json(json)
+      instantiate(JSON.parse(json))
+    end
+
+    def client
+      return context if context.is_a?(Lightspeed::Client)
+      account.client
+    end
+
+    def first(params: {})
+      params = params.merge(limit: 1)
+      instantiate(get(params: params)).first
+    end
+
+    def size(params: {})
+      params = params.merge(limit: 1, load_relations: nil)
+      get(params: params)['@attributes']['count'].to_i
+    end
+    alias_method :length, :size
+
+    def each_loaded
+      @resources ||= {}
+      @resources.each_value
+    end
+
+    def all_loaded
+      each_loaded.to_a
+    end
+
+    def first_loaded
+      each_loaded.first
+    end
+
+    def size_loaded
+      @resources.size
+    end
+
+    def all(params: {})
+      enum_page(params: params).to_a.flatten(1)
+    end
+
+    def each_page(per_page: PER_PAGE, params: {}, &block)
+      enum_page(per_page: per_page, params: params).each(&block)
+    end
+
+    def enum_page(per_page: PER_PAGE, params: {})
+      Enumerator.new do |yielder|
+        loop.with_index do |_, n|
+          resources = page(n, per_page: per_page, params: params)
+          yielder << resources
+          raise StopIteration if resources.length < per_page
+        end
+      end
+    end
+
+    def enum(per_page: PER_PAGE, params: {})
+      Enumerator.new do |yielder|
+        each_page(per_page: per_page, params: params) do |page|
+          page.each { |resource| yielder << resource }
+        end
+      end
+    end
+
+    def each(per_page: PER_PAGE, params: {}, &block)
+      enum(per_page: per_page, params: params).each(&block)
+    end
+
+    def find(id)
+      first(params: { resource_class.id_field => id }) || handle_not_found(id)
+    end
+
+    def create(attributes = {})
+      instantiate(post(body: attributes.to_json)).first
+    end
+
+    def update(id, attributes = {})
+      instantiate(put(id, body: attributes.to_json)).first
+    end
+
+    def destroy(id)
+      instantiate(delete(id)).first
+    end
+
+    def self.collection_name
+      name.demodulize
+    end
+
+    def self.resource_name
+      collection_name.singularize
+    end
+
+    def self.resource_class
+      "Lightspeed::#{resource_name}".constantize
+    end
+
+    def base_path
+      "#{account.base_path}/#{resource_name}"
+    end
+
+    def inspect
+      "#<#{self.class.name} API#{base_path}>"
+    end
+
+    def as_json(*args)
+      return if all_loaded.empty?
+      { resource_name => all_loaded.as_json(*args) }
+    end
+    alias_method :to_h, :as_json
+
+    def to_json(*args)
+      as_json.to_json(*args)
+    end
+
+    def page(n, per_page: PER_PAGE, params: {})
+      params = params.merge(limit: per_page, offset: per_page * n)
+      instantiate(get(params: params))
+    end
+
+    def load_relations_default
+      'all'
+    end
+
+    private
+
+    def handle_not_found(id)
+      raise Lightspeed::Error::NotFound, "Could not find a #{resource_name} with #{resource_class.id_field}=#{id}"
+    end
+
+    def context_params
+      if context.class.respond_to?(:id_field) &&
+         resource_class.method_defined?(context.class.id_field.to_sym)
+        { context.class.id_field => context.id }
+      else
+        {}
+      end
+    end
+
+    def instantiate(response)
+      return [] unless response.is_a?(Hash)
+      @resources ||= {}
+      Array.wrap(response[resource_name]).map do |resource|
+        resource = resource_class.new(context: self, attributes: resource)
+        @resources[resource.id] = resource
+      end
+    end
+
+    def resource_class
+      self.class.resource_class
+    end
+
+    def resource_name
+      self.class.resource_name
+    end
+
+    def get(params: {})
+      params = { load_relations: load_relations_default }
+        .merge(context_params)
+        .merge(params)
+        .reject { |_, v| v.nil? }
+      client.get(
+        path: collection_path,
+        params: params
+      )
+    end
+
+    def post(body:)
+      client.post(
+        path: collection_path,
+        body: body
+      )
+    end
+
+    def put(id, body:)
+      client.put(
+        path: resource_path(id),
+        body: body
+      )
+    end
+
+    def delete(id)
+      client.delete(
+        path: resource_path(id)
+      )
+    end
+
+    def collection_path
+      "#{base_path}.json"
+    end
+
+    def resource_path(id)
+      "#{base_path}/#{id}.json"
+    end
+  end
+end