infakt_api_client 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66db2a13b4235e6fad5d5b11a0b0b8cb70758b4097fd7e35f51e5c8e8a9ce3cc
-  data.tar.gz: ebfe4a31360ea49de885982d5ce9738b1e697bf4e212420bdef20ab48b53b10c
+  metadata.gz: f125465ce5bf7c15799e628c97fbb803bfb3e1f507bbedea65d66c49d709bbad
+  data.tar.gz: 9a3a34e5a354f458aa04f12395a63349bbc4249f2db2c921343e8125185f13f7
 SHA512:
-  metadata.gz: 6d3c23ca6ef5f48771e204ef78b02be6330f966f99725cbb63bf2d14b4d3bfec4fa2b382fcdb7dff3494fc153b390d8512a5301e20f68cb0a68740d60a8ce808
-  data.tar.gz: 604db6ec8ff9c70f9a361d4ad479b2c7fbc6295e6e9d2e4c155d3812ad2868d24c9599621643e9546e96a689d3b9f6e83340cba2807152f8bb0a14efc3ef4786
+  metadata.gz: bfde9c31d30ad643123927c01b83cbaffb13c002ae2649a58791729aa383f9b9a0cdc093fad7379f4d7103a31d090c600549c0f9da955eaf1a23d2e5ec0432fe
+  data.tar.gz: 004c824feecb65441245dfceb55b99229fd60b8a6dc0cfcf6dc67c904e532921c06083d008bf6970a3e03aa05929f8a025b7cc9e27c74954d4a6964f656a859d

data/README.md

@@ -1,9 +1,11 @@
 # InfaktApiClient
 
-A Ruby client library for the Infakt API, providing easy access to Infakt's invoicing and accounting services.
+A Ruby client library for the InFakt API, providing easy access to InFakt's invoicing and accounting services. This client supports both the production and sandbox environments of the InFakt API v3.
 
 ## Installation
 
+### In a Ruby Application
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -22,26 +24,82 @@ Or install it yourself as:
 $ gem install infakt_api_client
 ```
 
-## Usage
+### In a Rails Application
+
+After adding the gem to your Gemfile and running `bundle install`, you can run the generator to create an initializer:
+
+```bash
+$ rails generate infakt_api_client:install
+```
+
+This will create a configuration file at `config/initializers/infakt_api_client.rb`.
+
+## Configuration
 
-First, configure the client with your API key:
+Configure the client with your API key:
 
 ```ruby
 InfaktApiClient.configure do |config|
+  # Your API key from InFakt
   config.api_key = 'your_api_key_here'
+  
+  # Optional: Use sandbox mode for testing (default: false)
+  config.sandbox_mode = false
+  
+  # Optional: Override the API endpoint (not usually needed)
+  # config.api_endpoint = 'https://custom-endpoint.example.com/'
 end
 ```
 
-### Examples
+### Sandbox Mode
+
+For testing purposes, you can use the InFakt sandbox environment:
 
 ```ruby
-# Create a new client
-client = InfaktApiClient.new
+InfaktApiClient.configure do |config|
+  config.api_key = 'your_sandbox_api_key'
+  config.sandbox_mode = true
+end
+```
+
+## Usage Examples
+
+### Basic Usage
+
+```ruby
+# Create a client instance
+client = InfaktApiClient::Client.new
 
 # Fetch user details
 user = client.user_details
+puts "User email: #{user.account_data.email}"
+puts "Company name: #{user.company_data.company_name}"
 ```
 
+### Error Handling
+
+```ruby
+begin
+  client = InfaktApiClient::Client.new
+  user = client.user_details
+  # Process user data
+rescue InfaktApiClient::Error => e
+  puts "API Error: #{e.message}"
+end
+```
+
+## API Documentation
+
+For detailed information about the InFakt API endpoints and parameters, refer to the [official InFakt API documentation](https://docs.infakt.pl/).
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
 ## Documentation
 
 For detailed documentation of available methods and options, please visit our [Wiki](https://github.com/mateuszpalak/infakt_api_client/wiki).

data/lib/generators/infakt_api_client/install_generator.rb

@@ -3,12 +3,33 @@
 module InfaktApiClient
   module Generators
     # Generator that installs InfaktApiClient initializer into a Rails application
+    # @example Run the generator
+    #   rails generate infakt_api_client:install
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
+      desc "Creates an InfaktApiClient initializer for your Rails application"
 
       def copy_initializer
         template "initializer.rb", "config/initializers/infakt_api_client.rb"
       end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+
+      private
+
+      def readme(_path)
+        say ""
+        say "===============================================================================", :green
+        say "InfaktApiClient has been installed successfully!", :green
+        say "-------------------------------------------------------------------------------", :green
+        say "Please set your API key in config/initializers/infakt_api_client.rb", :yellow
+        say ""
+        say "For sandbox testing, set config.sandbox_mode = true", :yellow
+        say "===============================================================================", :green
+        say ""
+      end
     end
   end
 end

data/lib/generators/infakt_api_client/templates/initializer.rb

@@ -4,4 +4,8 @@
 InfaktApiClient.configure do |config|
   # Your InFakt API key. You can find it in your InFakt account settings
   config.api_key = "your_api_key_here"
+
+  # Set to true to use the sandbox environment for testing
+  # Default: false (uses production environment)
+  # config.sandbox_mode = false
 end

data/lib/infakt_api_client/client.rb

@@ -4,10 +4,19 @@ module InfaktApiClient
   # Client class for interacting with the inFakt API
   # Manages HTTP communication and authentication with the API endpoints
   class Client
-    # Add HTTP status constants for better readability
+    # HTTP status constants for better readability
     HTTP_OK = 200
+    HTTP_CREATED = 201
+    HTTP_ACCEPTED = 202
+    HTTP_NO_CONTENT = 204
+    HTTP_BAD_REQUEST = 400
     HTTP_UNAUTHORIZED = 401
+    HTTP_FORBIDDEN = 403
     HTTP_NOT_FOUND = 404
+    HTTP_UNPROCESSABLE_ENTITY = 422
+    HTTP_TOO_MANY_REQUESTS = 429
+    HTTP_INTERNAL_SERVER_ERROR = 500
+    HTTP_SERVICE_UNAVAILABLE = 503
 
     def initialize
       @connection = Faraday.new(url: InfaktApiClient.configuration.api_endpoint) do |faraday|
@@ -15,6 +24,8 @@ module InfaktApiClient
       end
     end
 
+    # Get user account details
+    # @return [User] User object with account details
     def user_details
       response = @connection.get("account/details.json")
       handle_response(response) do |data|
@@ -27,25 +38,48 @@ module InfaktApiClient
     def configure_connection(faraday)
       faraday.headers["X-inFakt-ApiKey"] = InfaktApiClient.configuration.api_key
       faraday.headers["Content-Type"] = "application/json"
+      faraday.headers["Accept"] = "application/json"
       faraday.adapter Faraday.default_adapter
       faraday.response :json # Automatically parse JSON responses
     end
 
     def handle_response(response)
       case response.status
-      when HTTP_OK
-        yield response.body # No need to parse JSON manually now
+      when HTTP_OK, HTTP_CREATED, HTTP_ACCEPTED, HTTP_NO_CONTENT
+        return yield({}) if response.body.nil? || response.body.empty?
+
+        yield response.body
+      when HTTP_BAD_REQUEST
+        raise Error, "Bad request - check your parameters: #{response.body}"
       when HTTP_UNAUTHORIZED
         raise Error, "Unauthorized - check your API key"
+      when HTTP_FORBIDDEN
+        raise Error, "Forbidden - you don't have permission to access this resource"
       when HTTP_NOT_FOUND
         raise Error, "Resource not found"
+      when HTTP_UNPROCESSABLE_ENTITY
+        raise Error, "Unprocessable entity: #{response.body}"
+      when HTTP_TOO_MANY_REQUESTS
+        raise Error, "Too many requests - rate limit exceeded"
+      when HTTP_INTERNAL_SERVER_ERROR
+        raise Error, "Internal server error"
+      when HTTP_SERVICE_UNAVAILABLE
+        raise Error, "Service unavailable - try again later"
       else
         raise Error, build_error_message(response)
       end
     end
 
     def build_error_message(response)
-      "API error (status: #{response.status}): #{response.body}"
+      message = "API error (status: #{response.status})"
+      if response.body.is_a?(Hash) && response.body["message"]
+        message += ": #{response.body["message"]}"
+      elsif response.body.is_a?(Hash) && response.body["error"]
+        message += ": #{response.body["error"]}"
+      elsif response.body.is_a?(String) && !response.body.empty?
+        message += ": #{response.body}"
+      end
+      message
     end
   end
 end

data/lib/infakt_api_client/configuration.rb

@@ -4,14 +4,23 @@ module InfaktApiClient
   # Configuration class for InfaktApiClient
   # Manages API credentials and endpoint settings for the inFakt API integration
   class Configuration
-    DEFAULT_ENDPOINT = "https://api.niebieskiorzel.pl/v3/"
+    DEFAULT_ENDPOINT = "https://api.infakt.pl/api/v3/"
+    SANDBOX_ENDPOINT = "https://api.sandbox-infakt.pl/api/v3/"
 
     attr_accessor :api_key
-    attr_reader :api_endpoint
+    attr_reader :api_endpoint, :sandbox_mode
 
     def initialize
       @api_endpoint = DEFAULT_ENDPOINT
       @api_key = nil
+      @sandbox_mode = false
+    end
+
+    # Enable or disable sandbox mode
+    # @param value [Boolean] true to enable sandbox mode, false to disable
+    def sandbox_mode=(value)
+      @sandbox_mode = !value.nil?
+      @api_endpoint = sandbox_mode ? SANDBOX_ENDPOINT : DEFAULT_ENDPOINT
     end
 
     def api_endpoint=(url)

data/lib/infakt_api_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module InfaktApiClient
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: infakt_api_client
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Mateusz Palak
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-13 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -38,7 +37,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: Prosty klient Ruby do integracji z API inFakt.pl
+description: A simple Ruby client for integrating with the InFakt.pl API
 email:
 - mateusz.palak@hotmail.com
 executables: []
@@ -58,7 +57,6 @@ homepage: https://github.com/mateuszpalak/infakt_api_client
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -73,8 +71,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.8
 specification_version: 4
-summary: Klient API dla systemu fakturowego inFakt.pl
+summary: API client for the InFakt.pl invoicing system
 test_files: []