moysklad 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f689b54410b1ea6bf38db44091bbfa37d9650a0d
-  data.tar.gz: 05e2e80d9a16a7f1b860318ca276a534b8b787a3
+  metadata.gz: 7ce9d5b8b1a5f1edb130458f589bc42a2a528785
+  data.tar.gz: 6e3d6bcccc02fe6d70b35fa1fb53776860130580
 SHA512:
-  metadata.gz: 462cde790f4f03d371c7e56e7d1a8540b8caee937b0fefbeff0d1099963205db2a4abe0b603a6516543c93c22798cc00f65db97afaf0cd8179bc4c82e9517775
-  data.tar.gz: 9221da267d8df68aa58688833da7e4b5948bfecd1c2c1e22af5f9002cf6a87fab3aa8f8f189d6a148700ad5761436b4414a32d6ad7f3b1e2a7a6656f3773bd06
+  metadata.gz: 011d7e2405fdd727a6546f52618ab3be16d06858c6f581f2f7ebef1ec0a51a9621c9ab88f338c7ffc137f471ffa392a06fdbe58f743a21dc9e5ae916fe17653c
+  data.tar.gz: bd7eebe8792ae0c4ddd0b5af4515ccbc792157d03a1c405e4477c70bdbd80c707435a36db1a2dffc53a5925c753a6318f5976b40c2e0196997c9028c99e54afc

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.1.4 / 2014-12-04
+
+* Universe.build для ленивого создания вселенной
+
 ## 0.1.3 / 2014-12-04
 
 * Примеры использования и больше документации

data/README.md

@@ -1,17 +1,22 @@
-# Правильный Ruby-клиент для API moysklad.ru
+#  Ruby-клиент для REST XML API Moysklad
 
 [![Build Status](https://travis-ci.org/BrandyMint/moysklad.svg)](https://travis-ci.org/BrandyMint/moysklad)
+[![Dependency Status](https://www.versioneye.com/user/projects/548225818674a4b5b90004dd/badge.svg?style=flat)](https://www.versioneye.com/user/projects/548225818674a4b5b90004dd)
+[![Code Climate](https://codeclimate.com/github/BrandyMint/moysklad/badges/gpa.svg)](https://codeclimate.com/github/BrandyMint/moysklad)
 
-Отличительные черты:
+* http://www.rubydoc.info/gems/moysklad
 
-* Модуль разработан согласно принципам SOLID. Легко расширяем.
-
-## Возможности
+## Особенности
 
-* Легкое внесение изменений (добавление новых моделей и ресурсов)
-* Удобный доступ ко всем действиям с ресурсами.
-* Кеширование ресурса со всеми записями (используем ресурс как локальную базу)
-* Понятные исключения при ошибках с сетью.
+* Модуль разработан согласно принципам SOLID. Легко расширяем.
+* Все используемые сущности описаны и структурированы. Например [Good](lib/moysklad/entities/good.rb)
+* Любые действия с ресурсами (Create, Read, Update, Delete, List).
+* Виртуальные действия с ресурсами (`where`, `findWhere`)
+* _Кеширование и предзагрузка_ ресурса со всеми записями (используем ресурс как локальную базу)
+* Работа с нескольмими аккаунтами на склада одновременно (отсуствие глобальных переменных).
+* Удобная работа с подресурсами (например справочником свойств товара)
+* _Ассоциации_ между сущностями автоматически получают данные по API (`good.features`).
+* [Client](lib/moysklad/client.rb) для прямого обращения к API в случае крайней необходимости.
 
 ## Установка
 
@@ -19,39 +24,48 @@
 
     gem 'moysklad'
 
-
 ## Использование
 
 Создаем благоприятное окружение для работы с API:
 
-> client = Moysklad::Client.new login:'ВАШ ЛОГИН', password:'ВАШ ПАРОЛЬ'
-> universe = Moysklad::Universe.new client: client
+```ruby
+universe = Moysklad::Universe.build login:'ВАШ ЛОГИН', password:'ВАШ ПАРОЛЬ'
+```
 
 ### Список элементов.
 
-Например список товаров.
+Например список товаров (`Good`).
 
-> universe.goods.list
-> => [Moysklad::Entities::Good, Moysklad::Entities::Good, ..]
+```ruby
+universe.goods.list
+# => [Moysklad::Entities::Good, Moysklad::Entities::Good, ..]
+```
 
 Обратите внимание, что список возвращается "как есть" и для работы с ним есть более удобные методы.
 
+Параметры списка.
+
+```ruby
+universe.stock.list slotUuid: uuid
+```
+
 Страница товаров:
 
-> page = universe.goods.page
-> => Moysklad::Entities::Page
+```ruby
+page = universe.goods.page
+# => Moysklad::Entities::Page
 
-> page.total
-> => 1280
+page.total
+# => 1280
 
-> page.count
-> => 1000
+page.count
+# => 1000
 
-> page.start
-> => 0
+page.start
+# => 0
 
-> page.items
-> =>[Moysklad::Entities::Good, ..]
+# page.items
+# =>[Moysklad::Entities::Good, ..]
 
 Есть очень удобная возможность автоматически загрузать ВСЕ товары с учетом пейджирования:
 
@@ -61,99 +75,198 @@
 
 > goods
 > => [Moysklad::Entities::Page]
-
+```
 
 ### Получить конкретный элемент
 
-> universe.goods.get $uuid
-> => [Moysklad::Entities::Good]
-
+```ruby
+universe.goods.get $uuid
+# => [Moysklad::Entities::Good]
+```
 
 ### Создаем элемент
 
 Например загрузка заказа покупателя:
 
-> co = Moysklad::Entities::CustomerOrder.new
-> co.vatIncluded = true
-> co.applicable  = true
-> co.customerOrderPosition = [Moysklad::Entities::CustomerOrderPosition.new]
->
-> created_order = universe.customer_orders.create co
-> => [Moysklad::Entities::Good]
-> created_order.uuid
-> => uuid нового заказа
+```
+co = Moysklad::Entities::CustomerOrder.new
+co.vatIncluded = true
+co.applicable  = true
+[...]
+co.customerOrderPosition = [Moysklad::Entities::CustomerOrderPosition.new]
+
+created_order = universe.customer_orders.create co
+# => [Moysklad::Entities::Good]
+
+created_order.uuid
+# => uuid нового заказа
+```
 
 ### Удаляем элемент
 
-> universe.goods.delete $uuid
+```ruby
+universe.goods.delete $uuid
+```
 
-### Кеширование
+### Кеширование и предзагрузка
 
 Одной из главных возможностей данного модуля является возможность работать с API как с базой данных,
 не выполняя запрос по получению каждого товара по-отдельности, и выдавать данные их кеша.
 
 Класический способ получить данные по товару делает GET запрос каждый раз:
 
-> > universe.goods.get $uuid
-> => Client: GET exchange/rest/ms/xml/Good/f24937e7-7ba1-11e4-90a2-8ecb000abf12 {}
-> => [Moysklad::Entities::Good]
+```ruby
+universe.goods.get $uuid
+# => Client: GET exchange/rest/ms/xml/Good/f24937e7-7ba1-11e4-90a2-8ecb000abf12 {}
+# => [Moysklad::Entities::Good]
+```
 
 Продвинутый способ вытаскивает все данные сразу и в дальнейшем берет обьекты из кеша:
 
-> > universe.goods.find $uuid
-> => Client: GET exchange/rest/ms/xml/Good/list {:start=>0}
-> => Client: GET exchange/rest/ms/xml/Good/list {:start=>1000}
-> => [Moysklad::Entities::Good]
+```ruby
+> universe.goods.find $uuid
+# => Client: GET exchange/rest/ms/xml/Good/list {:start=>0}
+# => Client: GET exchange/rest/ms/xml/Good/list {:start=>1000}
+# => [Moysklad::Entities::Good]
+```
 
 И в следующий раз API уже не дергается:
 
-> > universe.goods.find $another_uuid
-> => [Moysklad::Entities::Good]
+```ruby
+universe.goods.find $another_uuid
+# => [Moysklad::Entities::Good]
+```
 
 Это позволяет экономить на прямых запросах к API и избавляет нас от блокирования моимскладом по ограничению количества запросов за еденицу времени.
 
 
-### Список доступных ресутсов:
+## Поиск по фильтру
+
+Возвращает список элементов отображенных по фильтру:
+
+```ruby
+universe.features.where goodUuid: uuid
+# => [Moysklad::Enities::Feature, Moysklad::Enities::Feature]
+```
+
+Тоже самое, только возвращается первый элемент или nil:
+
+```ruby
+universe.features.findWhere goodUuid: uuid
+# => [Moysklad::Enities::Feature]
+```
 
-> universe.resources_list
-> => [:stock, :metadata, :custom_entity_metadata, :goods, :good_folders, :uoms, :countries,
+### Список доступных ресурсов:
+
+```ruby
+universe.resources_list
+# => [:stock, :metadata, :custom_entity_metadata, :goods, :good_folders, :uoms, :countries,
       :features, :custom_entities, :customer_orders, :warehouses, :companies,
       :consignments, :my_companies]
+```
 
+## Справочники и подресурсы
 
-## Pull Requests
+Доступ к Мойсклад устроен так, что некоторые справочники запрятаны в одной коллекции.
+Например если вы хотите получить все виды свойств товаров, то это можно сделать следующим образом.
+
+```ruby
+universe.metadata.subresource_by_name(:GoodFolder).all
+# => [Moysklad::Entities::AttributeMetadata, Moysklad::Entities::AttributeMetadata]
+```
+
+Или получить конкретное свойство:
 
-### Добавление новых моделей и ресутсрв
+```ruby
+universe.metadata.subresource_by_name(:GoodFolder).find uuid
+# => Moysklad::Entities::AttributeMetadata
+```
 
-Если в API моего склада есть справочник, который еще не добавлен в этот модуль, можете сделать это сами следующим образом.
+## Автоматическая обработка ассоциаций (отношения)
 
-Например добавляем Country.
+Нравятся `belongs_to` и `has_many` в рельсах? Тут есть почти тоже самое.
 
+```ruby
+feature = universe.features.find uuid
+feature.good
+# Client: GET exchange/rest/ms/xml/Good/f24937e7-7ba1-11e4-90a2-8ecb000abf12 {}
+# => [Moysklad::Entities::Good]
+```
+
+Пример как получить все данные по товару, включая модификации, свойства и их характеристики:
+
+```ruby
+good = universe.goods.find uuid
+# Client: GET exchange/rest/ms/xml/Good/f24937e7-7ba1-11e4-90a2-8ecb000abf12 {}
+
+good.features universe
+# Client: GET exchange/rest/ms/xml/Feature/list {}
+# => [Moysklad::Entities::Feature, ..]
+
+attribute = good.attributes.first
+# => [Moysklad::Entities::Attribute, ..]
+
+attribute.is_dictionary?
+# => true
+```
+
+Получаем вид свойства:
+
+```ruby
+attribute.metadata universe
+# Client: GET exchange/rest/ms/xml/Metadata/list {}
+# => [Moysklad::Entities::AttributeMetadata]
+```
+
+Получаем описание пользовательского справочника к которому принадлежит свойства
+
+```ruby
+dictionary = attribute.metadata(universe).dictionatyMetadata(universe)
+# Client: GET exchange/rest/ms/xml/CustomEntityMetadata/uuid {}
+# => [Moysklad::Entities::CustomEntityMetadata]
+```
+
+Значения всех элементов пользовательского справочника:
+
+```ruby
+dictionary.entities(universe)
+# => [Moysklad::Entities::CustomEntity, ...]
+```
+
+Подробнее смотри в исходниках сущностей.
+
+## Pull Requests
+
+### Добавление новых моделей и ресурсов.
+
+На данный момен в библиотеку добавлено 60% справочников используемых в моемскладе. Я добавляю новые справочники по мере необходимости. Но вы можете это сделать и сами следующим образом.
+
+Например добавляем `Country`.
 
 1. Добавляем в фикстуры пример выгрузки из API для тестирования и отладки:
 
-> MS_LOGON=логин MS_PASSWORD=пароль ./script/rest.sh Country list > ./spec/fixtures/Country_list.raw
+    MS_LOGON=логин MS_PASSWORD=пароль ./script/rest.sh Country list > ./spec/fixtures/Country_list.raw
 
 2. Создаем сущность на основе уже существующей, например good.rb
 
-> cp ./lib/moysklad/entities/good.rb ./lib/moysklad/entities/country.rb
+    cp ./lib/moysklad/entities/good.rb ./lib/moysklad/entities/country.rb
 
 3. Описываем свойства новой сущности Country.rb в терминах [nokogiri-happymapper](https://github.com/dam5s/happymapper)-а
 
-> vi ./lib/moysklad/entities/country.rb
+    vi ./lib/moysklad/entities/country.rb
 
 4. Добавляем сущность в requirements
 
-> vi ./lib/moysklad/entities.rb
+    vi ./lib/moysklad/entities.rb
 
 5. Содаем автоматический ресурс (имя ресурса во множественном числе)
 
-> vi ./lib/moysklad/resources.rb
+    vi ./lib/moysklad/resources.rb
 
 6. Делаем spec для сущности и для ресурса.
 
-> vi ./spec/lib/moysklad/resources/countries_spec.rb
-> vi ./spec/lib/moysklad/entities/country_spec.rb
+    > vi ./spec/lib/moysklad/resources/countries_spec.rb
+    > vi ./spec/lib/moysklad/entities/country_spec.rb
 
 7. Проверяем что тесты проходят.
 
@@ -161,13 +274,13 @@
 
 ## Тестирование
 
-> bundle exec guard
+    > bundle exec guard
 
 ## Полезняшки
 
 Скрипт для быстрого доступа к сервисам моего склада
 
-> MS_LOGON=логин MS_PASSWORD=пароль ./script/rest.sh Country list > ./spec/fixtures/Country_list.raw
+    > MS_LOGON=логин MS_PASSWORD=пароль ./script/rest.sh Country list > ./spec/fixtures/Country_list.raw
 
 ## Ссылочки
 
@@ -175,3 +288,7 @@
 * Документация для разработчииков https://support.moysklad.ru/hc/ru/sections/200561443-Разработчикам
 
 ## Присылайте пул-реквесты )
+
+## Авторство
+
+* Данил Письменный (brandymint.ru)

data/lib/moysklad/entities/attribute.rb

@@ -11,14 +11,24 @@ module Moysklad::Entities
     attribute :entityValueUuid, String
 
     # Объект описывающий тип атритуба
+    #
+    # @return Moysklad::Entities::AttributeMetadata
+    #
     def metadata universe
-      universe.metadata.subresource_by_name(:GoodFolder).find  metadataUuid
+      universe.metadata.subresource_by_name(:GoodFolder).find metadataUuid
     end
 
+    # Название свойства, полученное из AttributeMetadata
+    #
+    # @return String
+    #
     def attributeName universe
       metadata(universe).name
     end
 
+    # Значение свойства согласно его типу
+    #
+    # @return [String | Moysklad::Entities::CustomEntity | Integer | Decimal ]
     def get_value universe
       md = metadata universe
       case md.attrType
@@ -28,6 +38,7 @@ module Moysklad::Entities
         valueText
       when 'STRING'
         valueString
+        # TODO Другие типы
       else
         raise "Не известный тип мета-аттрибута #{md.uuid}: #{md.attrType}"
       end

data/lib/moysklad/entities/attribute_metadata.rb

@@ -15,10 +15,21 @@ module Moysklad::Entities
     attribute :required,            Boolean
     attribute :dictionaryMetadataUuid, String
 
+    def is_dictionary?
+      attrType == 'ID_CUSTOM'
+    end
+
+    # Если это свойство типа ID_CUSTOM, то возвращается пользовательский справочник
+    #
+    # @return Moysklad::Entities::CustomEntityMetadata
     def dictionatyMetadata universe
+      raise "Это свойства не типа справочник" unless dictionaryMetadataUuid
       universe.custom_entity_metadata.find dictionaryMetadataUuid
     end
 
+    # Справочник к которому принадлежит это ссвойство
+    #
+    # @return Moysklad::Entities::EmbeddedEntityMetadata
     def entityMetadata universe
       universe.metadata.find entityMetadataUuid
     end

data/lib/moysklad/entities/custom_entity_metadata.rb

@@ -1,6 +1,7 @@
 # https://online.moysklad.ru/exchange/rest/ms/xml/CustomEntityMetadata/list
 #
-# Пользовательские справочники
+# Пользовательский справочник
+#
 module Moysklad::Entities
   class CustomEntityMetadata < Base
     include CommonObject

data/lib/moysklad/entities/feature.rb

@@ -11,5 +11,10 @@ module Moysklad::Entities
     has_many  :attributes,  Moysklad::Entities::Attribute
     has_many  :barcodes,    Moysklad::Entities::Barcode
 
+    def good universe
+      cache :good, universe do
+        universe.good.find goodUuid
+      end
+    end
   end
 end

data/lib/moysklad/resources/base.rb

@@ -21,7 +21,7 @@ class Moysklad::Resources::Base
 
   # Возвращает список элементов как есть
   #
-  # @return Array[Moysklad::Entities::Base]
+  # @return [Array of Moysklad::Entities::Base]
   def list params={}
     parse client.get list_path, params
   end
@@ -51,9 +51,11 @@ class Moysklad::Resources::Base
   #
   # @param [Moysklad::Entities::Base]
   #
-  # @return [Moysklad::Entities::Base] созданная и возвращенная с сервера сущность
+  # Возвращается созданная на сервере сущность
+  #
+  # @return [Moysklad::Entities::Base]
   def create model
-    raise "Должна быть модель типа Moysklad::Entities::Base" unless model.is_a? Moysklad::Entities::Bae
+    raise "Должна быть модель типа Moysklad::Entities::Base" unless model.is_a? Moysklad::Entities::Base
     parse client.put create_path, prepare_resource(model)
   end
 

data/lib/moysklad/resources/indexed.rb

@@ -11,7 +11,7 @@ module Moysklad::Resources
 
     # Автоматически подгружает постранично данныез из API и возвращает их все сразу.
     #
-    # @return Array[Moysklad::Entities::Base]
+    # @return [Array of Moysklad::Entities::Base]
     def all
       @cached_list || pull_list
     end
@@ -26,7 +26,7 @@ module Moysklad::Resources
 
     # Перечень uuid-ов всех элементов в ресуресе
     #
-    # @return Array[uuid]
+    # @return [Array of uuids]
     def uuids
       index.keys
     end

data/lib/moysklad/resources/where_filter.rb

@@ -1,8 +1,19 @@
 module Moysklad::Resources::WhereFilter
+
+  # Возвращает список элементов по переданному фильтру.
+  # Например:
+  # > universe.features.where goodUuid: uuid
+  #
+  # @return [Array of Moysklad::Entities::Base]
+  #
   def where filter
     values.select { |v| filtered? v, filter }
   end
 
+  # Возвращает первый найденный по фильтру элемент или
+  # nil
+  #
+  # @return Moysklad::Entities::Base || nil
   def findWhere filter
     where(filter).first
   end

data/lib/moysklad/universe.rb

@@ -1,17 +1,27 @@
 module Moysklad
   class Universe
     cattr_reader :resources_list
+    attr_reader :client
 
-    def class_by_resource resource
-      "Moysklad::Resources::#{resource.to_s.singularize.capitalize}".constantize
-    end
-
+    # @param client[Moysklad::Client]
     def initialize client: nil
       raise "Должен быть client[Moysklad::Client]" unless client.is_a? Moysklad::Client
       @client = client
       @resources={}
     end
 
+    def self.client_class
+      Client
+    end
+
+    # Ленивое создание universe
+    #
+    # @param login
+    # @param password
+    def self.build login: nil, password: nil
+      new client: client_class.new(login: login, password: password)
+    end
+
     @@resources_list = []
     Moysklad::Resources.resources.each do |resource_klass|
       @@resources_list << resource_klass.pluralized_type.to_sym
@@ -20,10 +30,10 @@ module Moysklad
       end
     end
 
-    private
+    def class_by_resource resource
+      "Moysklad::Resources::#{resource.to_s.singularize.capitalize}".constantize
+    end
 
-    attr_reader :client
-    
   end
 
 end

data/lib/moysklad/version.rb

@@ -1,3 +1,3 @@
 module Moysklad
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/spec/lib/moysklad/universe_spec.rb

@@ -25,4 +25,20 @@ describe Moysklad::Universe do
     expect(subject.resources_list).to include(:features)
   end
 
+  describe '.build' do
+    let(:login)    { 'alala' }
+    let(:password) { 'ulala' }
+
+    subject { described_class.build login: login, password: password }
+
+    it do
+      expect(subject).to be_a Moysklad::Universe
+    end
+
+    it do
+      expect(subject.client).to be_a Moysklad::Client
+    end
+
+  end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moysklad
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Danil Pismenny
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-04 00:00:00.000000000 Z
+date: 2014-12-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler