pennylane 0.2.0.pre.alpha → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a60c1035dbad731707f86c3e97610c740d286cb8e6f70b7ac30709bbe29a0f0
-  data.tar.gz: b3fd35e53857c0d8df547bb361d4ae69bd1b73a482b7552232ab4cfcce5e8926
+  metadata.gz: d39d39c57d464e5c95acf6535e0e80508e9836fcbd8dd3afe49373283d965438
+  data.tar.gz: f4339e0fda690f67625aefb006f3964fdeefd8f125d9ff68ef26408cbb30caef
 SHA512:
-  metadata.gz: 903f576a32e59f954c68c255ce0aeacf6a820315f233f9825b2d35036cff3ab0928c6ac9fb0e84daa059da40dfde4f1829c5dff61ad58a57a406a3483e69b9e8
-  data.tar.gz: 72ed99e03c1d31ff1a871ebf0d335110c9a0a38a9acc9d8e14ecaf27a50731afef55ce6d1c77d89cbb0f95558eba121938ba8da7b87827e6c2416be10def3c5d
+  metadata.gz: 745d583286f8eeb20da9acb324ae2b7b0e2ca9611537c4aa340d674ad8c380428ee337e03c70c823940e61748520c7b5a267fa09a34493af4a6234a7ebded501
+  data.tar.gz: 4e671e89e28b95717eb5a800c4463896349eadf5756a1ebb11a69a645391881bb51f247960d9f6bd6e118a3386542796cf6646defaf7baafaa36a4d6152a8fc3

data/CHANGELOG.md

@@ -1,4 +1,17 @@
-## [Unreleased]
+## [1.0.1] - 2024-04-29
+- Fixed gem initialization issue (resources/*.rb) from a Rails app.
+
+## [1.0.0] - 2024-04-29
+
+- Support CustomerInvoice:
+  - `finalize`
+  - `mark_as_paid`
+  - `send_by_email`
+  - `links`
+  - `import`
+- Support per request `api_key` e.g `Pennylane::Customer.retrieve('cus_id', {api_key: 'x0fd....'})`
+- Endpoints returning empty response we are doing +1 GET request at the resource. Not the best solution but at least we are sure we have fresh data.
+- Added resource properties access with `#[]` e.g `cus['name']`
 
 ## [0.2.0-alpha] - 2024-04-20
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pennylane (0.2.0.pre.alpha)
+    pennylane (1.0.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -16,9 +16,22 @@ Install the gem and add to the application's Gemfile by executing:
     $ bundle add pennylane
 
 If bundler is not being used to manage dependencies, install the gem by executing:
+```ruby
+# Add to gemfile
+gem 'pennylane'
+```
+
+For Rails app :
+```ruby
+# Create initializers/pennylane.rb
+Pennylane.api_key = Rails.application.credentials.dig(:pennylane, :api_key)
 
-    $ gem install pennylane
+# Add credentials to config/credentials.yml.enc
+$ EDITOR=vim bin/rails credentials:edit
 
+pennylane:
+  api_key: 'x0fd....'
+```
 ## Requirements
 Ruby 2.3+.
 
@@ -32,7 +45,11 @@ Pennylane.api_key = 'x0fd....'
 
 # list customers
 Pennylane::Customer.list
+```
 
+### Customers ([API Doc](https://pennylane.readme.io/reference/customers-post-1))
+
+```ruby
 # filter and paginate customers
 Pennylane::Customer.list(filter: [{field: 'name', operator: 'eq', value: 'Apple'}], page: 2)
 
@@ -43,9 +60,131 @@ Pennylane::Customer.retrieve('38a1f19a-256d-4692-a8fe-0a16403f59ff')
 cus = Pennylane::Customer.retrieve('38a1f19a-256d-4692-a8fe-0a16403f59ff')
 cus.update(name: 'Apple Inc')
 
+# Create a customer
+Pennylane::Customer.create customer_type: 'company', name: 'Tesla', address: '4 rue du faubourg', postal_code: '75008', city: 'Paris', country_alpha2: 'FR'
+```
+
+### CustomerInvoices ([API Doc](https://pennylane.readme.io/reference/customer_invoices-import-1))
+
+```ruby
+# Create a customer invoice
+Pennylane::CustomerInvoice.create(
+  create_customer: true,
+  create_products: true,
+  invoice: {
+    date: '2021-01-01',
+    deadline: '2021-01-31',
+    customer: {
+      name: 'Tesla',
+      customer_type: 'company',
+      address: '4 rue du faubourg',
+      postal_code: '75001',
+      city: 'Paris',
+      country_alpha2: 'FR',
+      emails: ['stephane@tesla.com'] },
+    line_items: [
+      {
+        description: 'Consulting',
+        quantity: 1,
+        unit_price: 1000
+      }
+    ]
+  }
+)
+
+# List customer invoices
+Pennylane::CustomerInvoice.list
+
+# Retrieve a customer invoice
+invoice = Pennylane::CustomerInvoice.retrieve('38a1f19a-256d-4692-a8fe-0a16403f59ff')
+
+# Finalize a customer invoice
+invoice.finalize
+
+# Send a customer invoice
+invoice.send_by_email
+
+# Mark a customer invoice as paid
+invoice.mark_as_paid
+
+# Link an invoice and a credit note
+credit_note = Pennylane::CustomerInvoice.retrieve('some-credit-note-id')
+Pennylane::CustomerInvoice.links(invoice.quote_group_uuid, credit_note.quote_group_uuid)
+
+# Import a customer invoice
+Pennylane::CustomerInvoice.import(file: Util.file(File.expand_path('../fixtures/files/invoice.pdf', __FILE__)),
+                                  create_customer: true,
+                                  invoice: { date: Date.today, deadline: Date.today >> 1,
+                                             customer: {
+                                               name: 'Tesla',
+                                               customer_type: 'company',
+                                               address: '4 rue du faubourg',
+                                               postal_code: '75001',
+                                               city: 'Paris',
+                                               country_alpha2: 'FR',
+                                               emails: ['stephane@tesla.com'] },
+                                             line_items: [
+                                               {
+                                                 description: 'Consulting',
+                                                 quantity: 1,
+                                                 unit_price: 1000
+                                               }
+                                             ]
+                                  }
+)
+```
+### Suppliers ([API Doc](https://pennylane.readme.io/reference/suppliers-post))
+
+```ruby
+# Create a supplier
+Pennylane::Supplier.create(name: 'Apple Inc', address: '4 rue du faubourg', postal_code: '75008', city: 'Paris', country_alpha2: 'FR')
+
+# Retrieve a supplier
+Pennylane::Supplier.retrieve('supplier_id')
+
+# List all suppliers
+Pennylane::Supplier.list
+```
+
+### Products ([API Doc](https://pennylane.readme.io/reference/products-post-1))
+
+```ruby
+# Create a product
+Pennylane::Product.create(label: 'Macbook Pro', unit: 'piece', price: 2_999, vat_rate: 'FR_200', currency: 'EUR')
+
+# List all products
+Pennylane::Product.list
+
+# Retrieve a product
+product = Pennylane::Product.retrieve('product_id')
+
+# Update a product
+product.update(label: 'Macbook Pro 2021')
+```
+
+### Categories ([API Doc](https://pennylane.readme.io/reference/tags-get))
+
+```ruby
+# Create a category
+Pennylane::Category.create(name: 'IT')
+
+# Retrieve a category
+Pennylane::Category.retrieve('category_id')
+
+# List all categories
+Pennylane::Category.list
+
+# Update a category
+category = Pennylane::Category.retrieve('category_id')
+category.update(name: 'IT Services')
+```
+### CategoryGroups ([API Doc](https://pennylane.readme.io/reference/tag-groups-get))
+```ruby
+# List all category groups
+Pennylane::CategoryGroup.list
 ```
 
-### Per-request api key [TODO]
+### Per-request api key
 For apps that need to use multiple keys during the lifetime of a process. it's also possible to set a per-request key:
 ```ruby
 require "pennylane"
@@ -64,6 +203,19 @@ Pennylane::Customer.retrieve(
   }
 )
 
+```
+### Accessing resource properties
+
+Both indexer and accessors can be used to retrieve values of resource properties.
+
+```ruby
+customer = Pennylane::Customer.retrieve('customer_id')
+puts customer['name']
+puts customer.name
+
+# NOTE: To do this the gem will try to guess the key of the resource.
+# Otherwise we will have to do Pennylane::Customer.retrieve('customer_id').customer.name
+# We rely on `method_missing` to do Pennylane::Customer.retrieve('customer_id').name
 ```
 
 ## Test mode
@@ -72,14 +224,15 @@ Pennylane provide a [test environment](https://help.pennylane.com/fr/articles/18
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test-unit` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```bash
+bundle install
+bundle exec rake test
+```
 
 Resources implemented so far :
 ### CUSTOMER INVOICING
 
-- Customer Invoices 🚧
+- Customer Invoices ✅
 - Estimates 🚧
 - Billing Subscriptions 🚧
 

data/lib/pennylane/client.rb

@@ -3,7 +3,7 @@ module Pennylane
     BASE_URI = 'app.pennylane.com/api/external'.freeze
     VERSION = 'v1'.freeze
 
-    attr_accessor :key, :version
+    attr_accessor :version
 
     def initialize(key, version: 'v1')
       @key = key
@@ -21,7 +21,7 @@ module Pennylane
     end
 
 
-    def authorization
+    def authorization(key)
       "Bearer #{key}"
     end
     def http
@@ -34,8 +34,8 @@ module Pennylane
       Net::HTTP.const_get(method.to_s.capitalize)
     end
 
-    def request method, path, params:, opts: {}
-      req = initialize_request(method, path, params[:query]).tap do |req|
+    def request method, path, params: {}, opts: {}
+      req = initialize_request(method, path, params[:query], opts).tap do |req|
         req.body = params[:body].to_json if params[:body]
       end
 
@@ -61,10 +61,11 @@ module Pennylane
     def should_handle_as_error?(code)
       code.to_i >= 400
     end
-    def initialize_request method=nil, path=nil, params={}
+
+    def initialize_request method=nil, path=nil, params={}, opts={}
       klass(method).new(url(path, params)).tap do |request|
         request["content-type"] = 'application/json'
-        request["authorization"] = authorization
+        request["authorization"] = authorization(opts.fetch(:api_key, @key))
       end
     end
 

data/lib/pennylane/list_object.rb

@@ -19,7 +19,7 @@ module Pennylane
     end
 
     def key_for(resp)
-      resp.keys.find { |k| Pennylane::API_RESOURCES.keys.include?(Util.singularize(k.to_s)) } || resp.keys.find { |k| resp[k].is_a? Array }
+      resp.keys.find { |k| Pennylane::ObjectTypes.object_names_to_classes.keys.include?(Util.singularize(k.to_s)) } || resp.keys.find { |k| resp[k].is_a? Array }
     end
 
   end

data/lib/pennylane/object.rb

@@ -86,9 +86,7 @@ module Pennylane
       when Pennylane::Object
         obj.class.build_from(
           deep_copy(obj.instance_variable_get(:@values)),
-          obj.instance_variable_get(:@opts).select do |k, _v|
-            Util::OPTS_COPYABLE.include?(k)
-          end
+          obj.instance_variable_get(:@opts)
         )
       else
         obj

data/lib/pennylane/object_types.rb

@@ -0,0 +1,15 @@
+module Pennylane
+  module ObjectTypes
+    def self.object_names_to_classes
+      {
+        ListObject.object_name => ListObject,
+        Category.object_name => Category,
+        CategoryGroup.object_name => CategoryGroup,
+        Customer.object_name => Customer,
+        CustomerInvoice.object_name => CustomerInvoice,
+        Product.object_name => Product,
+        Supplier.object_name => Supplier
+      }.freeze
+    end
+  end
+end

data/lib/pennylane/resources/base.rb

@@ -1,6 +1,7 @@
 module Pennylane
   module Resources
     class Base < Pennylane::Object
+
       class << self
 
         def object_name
@@ -13,25 +14,26 @@ module Pennylane
 
         def request_pennylane_object(method:, path:, params: {}, opts: {}, usage: [], with: {})
           resp, opts = execute_resource_request(method, path, params, opts, usage)
-          Util.convert_to_pennylane_object(Util.normalize_response(resp, with), params, opts)
+          if resp.empty?
+            {}
+          else
+            Util.convert_to_pennylane_object(Util.normalize_response(resp, with), params, opts)
+          end
         end
 
         def execute_resource_request(method, path, params = {}, opts = {}, usage = [])
-          api_key = opts.delete(:api_key) || Pennylane.api_key
-
-
           resp = client.request(
             method,
             path,
             params: params,
             opts: opts
           )
-
-          [JSON.parse(resp.read_body), opts]
+          [JSON.parse(resp.read_body || "{}"), opts] # in case body is nil ew return an empty hash
         end
 
         def client
-          @client ||= Pennylane::Client.new(Pennylane.api_key)
+          @client ||= {}
+          @client[Pennylane.api_key] ||= Pennylane::Client.new(Pennylane.api_key)
         end
 
         def normalize_filters(filters)
@@ -47,6 +49,11 @@ module Pennylane
         super
       end
 
+      # object happens to be nil when the object is the nested object
+      def [](k)
+        (object && object[k.to_sym]) || @values[k.to_sym]
+      end
+
       #
       def object
         @values[self.class.object_name.to_sym]

data/lib/pennylane/resources/customer_invoice.rb

@@ -20,26 +20,71 @@ module Pennylane
         request_pennylane_object(method: :post, path: "/customer_invoices", params: { body: params }, opts: opts, with: { invoice: 'customer_invoice' })
       end
 
+      def import params, opts={}
+        request_pennylane_object(method: :post, path: "/customer_invoices/import", params: { body: params }, opts: opts, with: { invoice: 'customer_invoice' })
+      end
+
+      def links(*quote_group_uuids, opts: {})
+        request_pennylane_object(method: :post, path: "/customer_invoices/links", params: { body: { quote_group_uuids: quote_group_uuids } },
+                                                                                opts: {})
+      end
+    end
+
+    # since object name is different from the class name, we need to override the object_name method
+    def object
+      @values[:invoice]
     end
 
+    # doesnt have a `source_id` so we override it
+    def id
+      object.id
+    end
+
+    # API CALLS
+
     # since object name is different from the class name, we need to override the method
     def update(attributes)
-      resp, opts = self.class.request_pennylane_object(method: :put, path: "/#{self.class.object_name_plural}/#{id}",
+      resp, opts = self.class.request_pennylane_object(method: :put,
+                                                       path: "/customer_invoices/#{id}",
                                                        params: { body: { 'invoice' => attributes } },
                                                        opts: {}, with: { invoice: 'customer_invoice' })
       @values = resp.instance_variable_get :@values
       self
     end
 
-    # since object name is different from the class name, we need to override the object_name method
-    def object
-      @values[:invoice]
+    def finalize
+      request_and_retrieve(method: :put, path: "/customer_invoices/#{id}", action: 'finalize')
     end
 
-    # doesnt have a `source_id` so we override it
-    def id
-      object.id
+    def mark_as_paid
+      resp, opts = self.class.request_pennylane_object(method: :put,
+                                          path: "/customer_invoices/#{id}/mark_as_paid",
+                                          params: {},
+                                          opts: {}, with: { invoice: 'customer_invoice' })
+      @values = resp.instance_variable_get :@values
+      self
     end
 
+    def send_by_email
+      request_and_retrieve(method: :post, path: "/customer_invoices/#{id}", action: 'send_by_email')
+    end
+
+    private
+
+    # When API returns an empty body
+    # so we need to skip values assignment from the response
+    # GET /customer_invoices/:id again to get the updated values
+    def request_and_retrieve(method:, path:, action:)
+      self.class.request_pennylane_object(method: method,
+                                          path: "#{path}/#{action}",
+                                          params: {},
+                                          opts: {}, with: { invoice: 'customer_invoice' })
+      resp, opts = self.class.request_pennylane_object(method: :get,
+                                                       path: path,
+                                                       params: {},
+                                                       opts: {}, with: { invoice: 'customer_invoice' })
+      @values = resp.instance_variable_get :@values
+      self
+    end
   end
 end

data/lib/pennylane/util.rb

@@ -58,6 +58,11 @@ module Pennylane
         end
       end
 
+      def file(file_path)
+        file_data = File.open(file_path).read
+        Base64.strict_encode64(file_data)
+      end
+
       # This method is used to convert the keys of a hash from strings to symbols
       def symbolize_names(object)
         case object
@@ -80,7 +85,7 @@ module Pennylane
       end
 
       def klass_for(object)
-        Pennylane::API_RESOURCES[singularize(object)] || Pennylane::Object
+        Pennylane::ObjectTypes.object_names_to_classes[singularize(object)] || Pennylane::Object
       rescue
         Pennylane::Object
       end

data/lib/pennylane/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pennylane
-  VERSION = "0.2.0-alpha"
+  VERSION = "1.0.1"
 end

data/lib/pennylane.rb

@@ -11,8 +11,9 @@ require 'forwardable'
 require 'uri'
 require 'net/http'
 
-Dir["./lib/pennylane/resources/*.rb"].each {|file| require file }
+Dir[File.join(__dir__, 'pennylane/resources/*.rb')].each {|file| require file }
 
+require 'pennylane/object_types'
 
 module Pennylane
   class Error < StandardError; end
@@ -20,16 +21,6 @@ module Pennylane
   class ConfigurationError < Error; end
   class NotFoundError < Error; end
 
-  API_RESOURCES = {
-    ListObject.object_name => ListObject,
-    Category.object_name => Category,
-    CategoryGroup.object_name => CategoryGroup,
-    Customer.object_name => Customer,
-    CustomerInvoice.object_name => CustomerInvoice,
-    Product.object_name => Product,
-    Supplier.object_name => Supplier
-  }.freeze
-
   @config = Pennylane::Configuration.new
   # So we can have a module Pennylane that can be a class as well Pennylane.api_key = '1234'
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pennylane
 version: !ruby/object:Gem::Version
-  version: 0.2.0.pre.alpha
+  version: 1.0.1
 platform: ruby
 authors:
 - Stephane Bounmy
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-20 00:00:00.000000000 Z
+date: 2024-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: vcr
@@ -87,6 +87,7 @@ files:
 - lib/pennylane/configuration.rb
 - lib/pennylane/list_object.rb
 - lib/pennylane/object.rb
+- lib/pennylane/object_types.rb
 - lib/pennylane/resources/base.rb
 - lib/pennylane/resources/category.rb
 - lib/pennylane/resources/category_group.rb
@@ -116,9 +117,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.4.10
 signing_key: