cashctrl 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a3babb2af59d87a65c8320a5b88625fec3c98bb8c07b601e8fa454f4490f649
-  data.tar.gz: e61d18fe574d86ddba6453c87cbd6b2bce55817b03cfc65aedc68e66b0c8bbbf
+  metadata.gz: '019f213f238694c48c7204599a63e13e4f8fcea1a0eb337c649544bfa7b8172e'
+  data.tar.gz: bfb12a268305a238032dce7d0c8fd3f7a314f6a7df0b86629f560f8179275001
 SHA512:
-  metadata.gz: 6c80bba5143a5b62aeb333925cf1e4ae444afb53e60833ffd94330b8ee9e209fced19104a845b72275025555a0b609201baf931a8b6472632204e3ff7ff1dc04
-  data.tar.gz: f7bcfb1277d2e0883da53b155b69114755dd558bf4e7ec2a6dbc19e27fb55bbc027764bc37b036ab79d460c05cbcb561613da4e31f8949176fb642d653835d7d
+  metadata.gz: df078461cff3447464efd49e7867c363a6244170902fd9953b10056007e0640e03c5314011cef577f4aec1107383790e86d8d535807601de500e0199b4bd4e03
+  data.tar.gz: 32e23fc1a02ac10951e242145fc4c75f151ee7df572b34d97834df508bd80f7562c1cc0a4f035b0fc0cc9f71500955f9567ec5406bc08cb74a32148e552c0bf8

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Marco Roth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,39 +1,574 @@
-# Cashctrl
+# CashCtrl Ruby
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/cashctrl`. To experiment with that code, run `bin/console` for an interactive prompt.
+A Ruby gem to interact with the [CashCtrl](https://cashctrl.com) Swiss accounting software API.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add this line to your application's Gemfile:
+
+```ruby
+gem "cashctrl"
+```
 
-Install the gem and add to the application's Gemfile by executing:
+And then execute:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle install
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or install it yourself as:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install cashctrl
+```
+
+## Configuration
+
+### Global Configuration
+
+```ruby
+Cashctrl.configure do |config|
+  config.org = "your-organization"
+  config.api_key = ENV["CASHCTRL_API_KEY"]
+  config.language = "en"
+end
+```
+
+- `org` - Your CashCtrl subdomain
+- `api_key` - Your API key
+- `language` - Optional: `en`, `de`, `fr`, `it` (default: `en`)
+
+### Per-Client Configuration
+
+For multi-tenant applications or testing:
+
+```ruby
+client = Cashctrl::Client.new(
+  org: "other-organization",
+  api_key: "different-api-key",
+  language: "de"
+)
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Two API Styles
+
+The gem supports two usage patterns:
+
+#### 1. Class Methods (uses global configuration)
+
+**List all accounts:**
+
+```ruby
+Cashctrl::Account.list
+```
+
+**Read a specific account:**
+
+```ruby
+Cashctrl::Account.read(id: 1)
+```
+
+**Create an account:**
+
+```ruby
+Cashctrl::Account.create(number: "1000", name: "Cash", categoryId: 1)
+```
+
+**Update an account:**
+
+```ruby
+Cashctrl::Account.update(id: 1, name: "Updated Name")
+```
+
+**Delete accounts:**
+
+```ruby
+Cashctrl::Account.delete(ids: [1, 2, 3])
+```
+
+#### 2. Client Instance (custom configuration)
+
+```ruby
+client = Cashctrl::Client.new(org: "myorg", api_key: "key")
+
+client.accounts.list
+client.accounts.read(id: 1)
+client.accounts.create(number: "1000", name: "Cash", categoryId: 1)
+client.persons.list
+client.orders.list
+```
+
+#### Convenience Methods
+
+All resources support these shortcuts and aliases:
+
+```ruby
+Cashctrl::Account.all            # alias for .list
+Cashctrl::Account.find(1)        # alias for .read(id: 1)
+
+Cashctrl::Account.first          # alias for .list.first
+Cashctrl::Account.last           # alias for .list.last
+
+client.accounts.all
+client.accounts.find(1)
+client.orders.first
+```
+
+### Core Resources
+
+#### Accounts
+
+**List accounts:**
+
+```ruby
+Cashctrl::Account.list
+```
+
+**Get first or last account:**
+
+```ruby
+Cashctrl::Account.first
+Cashctrl::Account.last
+```
+
+**Find account by number:**
+
+```ruby
+Cashctrl::Account.find_by_number("1000")
+```
+
+**Get account balance:**
+
+```ruby
+Cashctrl::Account.balance(id: 1, date: "2024-12-31")
+```
+
+**Account categories:**
+
+```ruby
+Cashctrl::Account::Category.list
+Cashctrl::Account::Category.tree
+```
+
+**Bank accounts:**
+
+```ruby
+Cashctrl::Account::Bank.list
+Cashctrl::Account::Bank.create(name: "Main Bank", accountId: 1)
+```
+
+**Cost centers:**
+
+```ruby
+Cashctrl::Account::CostCenter.list
+Cashctrl::Account::CostCenter.balance(id: 1)
+```
+
+#### Persons (Contacts)
+
+```ruby
+Cashctrl::Person.list
+Cashctrl::Person.read(id: 1)
+Cashctrl::Person.create(firstName: "John", lastName: "Doe", isCustomer: true)
+Cashctrl::Person.categorize(ids: [1, 2], target: 5)
+```
+
+**Person categories:**
+
+```ruby
+Cashctrl::Person::Category.list
+Cashctrl::Person::Category.tree
+```
+
+**Titles (Mr., Mrs., etc.):**
+
+```ruby
+Cashctrl::Person::Title.list
+```
+
+#### Orders (Invoices, Quotes, etc.)
+
+```ruby
+Cashctrl::Order.list
+Cashctrl::Order.read(id: 1)
+Cashctrl::Order.create(
+  associateId: 1,
+  categoryId: 1,
+  items: [{ accountId: 100, name: "Service", unitPrice: 100 }].to_json
+)
+Cashctrl::Order.update_status(id: 1, status: "S")
+```
+
+**Order documents (PDF generation):**
+
+```ruby
+Cashctrl::Order::Document.read(id: 1)
+Cashctrl::Order::Document.read_pdf(id: 1)
+Cashctrl::Order::Document.mail(id: 1, recipientEmail: "client@example.com")
+```
+
+**Order categories:**
+
+```ruby
+Cashctrl::Order::Category.list
+```
+
+#### Journal Entries
+
+```ruby
+Cashctrl::Journal.list
+Cashctrl::Journal.read(id: 1)
+```
+
+**Create with account IDs:**
+
+```ruby
+Cashctrl::Journal.create(
+  debitId: 1,
+  creditId: 2,
+  amount: 100.00,
+  dateAdded: "2024-01-15",
+  title: "Payment received"
+)
+```
+
+**Create with account numbers:**
+
+```ruby
+Cashctrl::Journal.create(
+  debit: "1000",
+  credit: "2000",
+  amount: 100.00,
+  dateAdded: "2024-01-15",
+  title: "Payment received"
+)
+```
+
+**Create with Account objects:**
+
+```ruby
+cash_account = Cashctrl::Account.find_by_number("1000")
+bank_account = Cashctrl::Account.find_by_number("1020")
+
+Cashctrl::Journal.create(
+  debit: cash_account,
+  credit: bank_account,
+  amount: 500.00,
+  dateAdded: "2024-01-15",
+  title: "Cash deposit"
+)
+```
+
+#### Currencies
+
+```ruby
+Cashctrl::Currency.list
+Cashctrl::Currency.read(id: 1)
+Cashctrl::Currency.exchange_rate(from: "CHF", to: "EUR", date: "2024-01-15")
+```
+
+#### Tax Rates
+
+```ruby
+Cashctrl::Tax.list
+Cashctrl::Tax.read(id: 1)
+Cashctrl::Tax.create(name: "VAT 8.1%", percentage: 8.1)
+```
+
+#### Fiscal Periods
+
+```ruby
+Cashctrl::FiscalPeriod.list
+Cashctrl::FiscalPeriod.result(id: 1)
+Cashctrl::FiscalPeriod.switch(id: 2)
+Cashctrl::FiscalPeriod.complete(id: 1)
+Cashctrl::FiscalPeriod.book_depreciations(id: 1)
+```
+
+#### Reports
+
+```ruby
+Cashctrl::Report.tree
+```
+
+**Report collections:**
+
+```ruby
+Cashctrl::Report::Collection.read(id: 1)
+Cashctrl::Report::Collection.download_pdf(id: 1)
+Cashctrl::Report::Collection.download_annual_report(id: 1)
+```
+
+**Report elements:**
+
+```ruby
+Cashctrl::Report::Element.read(id: 1)
+Cashctrl::Report::Element.data(id: 1)
+Cashctrl::Report::Element.download_xlsx(id: 1)
+```
+
+#### Inventory
+
+**Articles:**
+
+```ruby
+Cashctrl::Resources::Inventory::Article.list
+Cashctrl::Resources::Inventory::Article.create(name: "Product", unitPrice: 50.00)
+```
+
+**Fixed assets:**
+
+```ruby
+Cashctrl::Resources::Inventory::Asset.list
+```
+
+**Units:**
+
+```ruby
+Cashctrl::Resources::Inventory::Unit.list
+```
+
+#### Files
+
+```ruby
+client.files.list
+client.files.get(id: 1)
+client.files.prepare(mime_type: "application/pdf", name: "invoice.pdf")
+client.files.persist(ids: [1])
+```
+
+### Typed Models & Collections
+
+API responses are automatically converted to typed Ruby objects.
+
+**List returns a Collection:**
+
+```ruby
+accounts = Cashctrl::Account.list
+accounts.class
+accounts.total
+accounts.each { |a| puts a.name }
+```
+
+**Individual records are typed models:**
+
+```ruby
+account = accounts.first
+account.class
+account.id
+account.name
+account.number
+```
+
+**Read also returns typed models:**
+
+```ruby
+account = Cashctrl::Account.read(id: 1)
+account.class
+```
+
+#### Type Coercion
+
+Fields are automatically converted to appropriate Ruby types.
+
+**DateTime fields:**
+
+```ruby
+account = Cashctrl::Account.read(id: 1)
+account.created
+account.last_updated
+```
+
+**BigDecimal for monetary values:**
+
+```ruby
+account.opening_amount
+account.end_amount
+```
+
+**Booleans:**
+
+```ruby
+account.is_inactive
+```
+
+**Date fields:**
+
+```ruby
+person = Cashctrl::Person.read(id: 1)
+person.date_birth
+```
+
+#### Accessing Raw API Response
+
+The original API response is always available:
+
+```ruby
+account = Cashctrl::Account.read(id: 1)
+account.raw_data
+```
+
+### Localized Strings (i18n)
+
+CashCtrl returns multi-language strings in XML format. These are automatically parsed into `LocalizedString` objects.
+
+**Localized fields return LocalizedString objects:**
+
+```ruby
+account = Cashctrl::Account.read(id: 1)
+account.category_display.class
+```
+
+**Access specific languages:**
+
+```ruby
+account.category_display.de
+account.category_display.en
+account.category_display.fr
+account.category_display.it
+```
+
+**`to_s` returns the value for the current locale:**
+
+```ruby
+account.category_display.to_s
+```
+
+**Get all translations as a hash:**
+
+```ruby
+account.category_display.to_h
+```
+
+The locale is determined by (in order of priority):
+1. `I18n.locale` if I18n is available
+2. `Cashctrl.configuration.language`
+3. Falls back to `"en"`
+
+### Export Formats
+
+Many list endpoints support CSV, Excel, and PDF exports:
+
+```ruby
+client.accounts.list_csv
+client.accounts.list_xlsx
+client.accounts.list_pdf
+```
+
+### Error Handling
+
+```ruby
+begin
+  Cashctrl::Account.read(id: 999999)
+rescue Cashctrl::AuthenticationError => e
+  puts "Invalid API key"
+rescue Cashctrl::NotFoundError => e
+  puts "Resource not found"
+rescue Cashctrl::ValidationError => e
+  puts "Validation failed"
+  puts e.errors
+rescue Cashctrl::RateLimitError => e
+  puts "Too many requests"
+rescue Cashctrl::ServerError => e
+  puts "Server error (5xx)"
+rescue Cashctrl::Error => e
+  puts "Generic error"
+end
+```
+
+### All Available Resources
+
+| Resource | Class |
+|----------|-------|
+| Accounts | `Cashctrl::Account` |
+| Account Banks | `Cashctrl::Account::Bank` |
+| Account Categories | `Cashctrl::Account::Category` |
+| Cost Centers | `Cashctrl::Account::CostCenter` |
+| Currencies | `Cashctrl::Currency` |
+| Custom Fields | `Cashctrl::CustomField` |
+| Files | `Cashctrl::Resources::CashctrlFile` |
+| Fiscal Periods | `Cashctrl::FiscalPeriod` |
+| History | `Cashctrl::Resources::History` |
+| Inventory Articles | `Cashctrl::Resources::Inventory::Article` |
+| Inventory Assets | `Cashctrl::Resources::Inventory::Asset` |
+| Inventory Units | `Cashctrl::Resources::Inventory::Unit` |
+| Journal | `Cashctrl::Journal` |
+| Locations | `Cashctrl::Location` |
+| Orders | `Cashctrl::Order` |
+| Order Categories | `Cashctrl::Order::Category` |
+| Order Documents | `Cashctrl::Order::Document` |
+| Persons | `Cashctrl::Person` |
+| Person Categories | `Cashctrl::Person::Category` |
+| Person Titles | `Cashctrl::Person::Title` |
+| Reports | `Cashctrl::Report` |
+| Report Collections | `Cashctrl::Report::Collection` |
+| Report Elements | `Cashctrl::Report::Element` |
+| Roundings | `Cashctrl::Rounding` |
+| Salary (all sub-resources) | `Cashctrl::Resources::Salary::*` |
+| Sequence Numbers | `Cashctrl::SequenceNumber` |
+| Settings | `Cashctrl::Setting` |
+| Tax Rates | `Cashctrl::Tax` |
+| Text Templates | `Cashctrl::Text` |
+
+## API Documentation
+
+For full API documentation, see the [CashCtrl API Reference](https://app.cashctrl.com/static/help/en/api/index.html).
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Model Generator
+
+Model classes are auto-generated from `lib/cashctrl/schema.yml`. The schema defines attributes and their types for each resource.
+
+**Schema format:**
+
+```yaml
+account:
+  attributes:
+    id:
+      type: integer
+      readonly: true
+    number:
+      type: string
+    name:
+      type: string
+    opening_amount:
+      type: decimal
+    created:
+      type: datetime
+      readonly: true
+    is_inactive:
+      type: boolean
+```
+
+**Supported types:**
+
+- `string` - Plain strings (auto-detects localized XML strings)
+- `integer` - Integer values
+- `decimal` - BigDecimal for monetary values
+- `boolean` - Boolean values
+- `date` - Date objects
+- `datetime` - DateTime objects
+- `json` - JSON parsed objects
+
+**Regenerate models after schema changes:**
+
+```bash
+ruby lib/generators/model_generator.rb
+```
+
+This generates model classes in `lib/cashctrl/models/` with proper type coercion.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/marcoroth/cashctrl. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/marcoroth/cashctrl/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/marcoroth/cashctrl-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/marcoroth/cashctrl-ruby/blob/main/CODE_OF_CONDUCT.md).
 
-## Code of Conduct
+## License
 
-Everyone interacting in the Cashctrl project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/marcoroth/cashctrl/blob/main/CODE_OF_CONDUCT.md).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).