moloni 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0fd2b46790ffa005a63b070cd61e841afb66f72ecacb6d0616d2ed95af2a19e4
+  data.tar.gz: 6461230850e14c022010e9021948b20789958c2f3ee74cb3ba834713240e480c
+SHA512:
+  metadata.gz: be6798d96a26ebde2d5f714d8216cea066797af66e4e10d23519200bf26fa2af0c99ca005abaf6241ccddbbfea0065edb767e86f80fc6cede7a33e7dde51db78
+  data.tar.gz: f6d873d8bfb6045d3dccbdda1873761fa3c955b1ed35ef8684f90f152adc970039008f74ee7e0cfa0bb5f05e44872a1d5d05010fbcda05f904e84193f9b984ab

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.env
+/cache/*
+Gemfile.lock
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,4 @@
+--format documentation
+--color
+--require spec_helper
+--order rand

data/.rubocop.yml

@@ -0,0 +1,76 @@
+require: rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.2
+  SuggestExtensions: false
+
+Lint:
+  Exclude:
+    - bin/*
+
+# Don't force top level comments in every class
+Style/Documentation:
+  Enabled: false
+
+
+# A good line length is 100 chars
+Layout/LineLength:
+  Max: 100
+  AllowURI: true
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 300
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Metrics/AbcSize:
+  Max: 30
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Max: 10
+
+Lint/DuplicateBranch: # (new in 1.3)
+  Enabled: true
+Lint/DuplicateRegexpCharacterClassElement: # (new in 1.1)
+  Enabled: true
+Lint/EmptyBlock: # (new in 1.1)
+  Enabled: true
+Lint/EmptyClass: # (new in 1.3)
+  Enabled: true
+Lint/NoReturnInBeginEndBlocks: # (new in 1.2)
+  Enabled: true
+Lint/ToEnumArguments: # (new in 1.1)
+  Enabled: true
+Lint/UnexpectedBlockArity: # (new in 1.5)
+  Enabled: true
+Lint/UnmodifiedReduceAccumulator: # (new in 1.1)
+  Enabled: true
+Style/ArgumentsForwarding: # (new in 1.1)
+  Enabled: true
+Style/CollectionCompact: # (new in 1.2)
+  Enabled: true
+Style/DocumentDynamicEvalDefinition: # (new in 1.1)
+  Enabled: true
+Style/NegatedIfElseCondition: # (new in 1.2)
+  Enabled: true
+Style/NilLambda: # (new in 1.3)
+  Enabled: true
+Style/RedundantArgument: # (new in 1.4)
+  Enabled: true
+Style/SwapValues: # (new in 1.1)
+  Enabled: true

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.7.1
+before_install: gem install bundler -v 2.1.4

data/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md
+
+> Compact instructions for working in this Ruby gem.
+
+## Project type
+Ruby gem wrapping the [Moloni API](https://www.moloni.pt/dev/). Version 0.5.0 requires Ruby >= 3.2.
+
+## Setup
+```bash
+bin/setup            # bundle install
+```
+
+## Development commands
+```bash
+rake spec            # run rspec tests (default rake task)
+bundle exec rspec    # run rspec tests
+bundle exec rubocop  # lint
+```
+
+## Environment / secrets
+- `spec/spec_helper.rb` resets `Moloni.config` before every test and seeds default test credentials.
+- Tests use WebMock; no live credentials or VCR cassettes are needed.
+- `bin/auth` initiates the OAuth callback flow using `DEVELOPER_ID` and `CLIENT_SECRET`.
+
+## Architecture notes
+- Entrypoint: `lib/moloni.rb` configures a Faraday connection to `https://api.moloni.pt/v1/` and autoloads all models.
+- `Moloni::BaseModel` is the core engine. It handles token auto-refresh, POST-only requests, `human_errors=true` by default, and **dynamic dispatch** via `method_missing` so any new Moloni API method works without adding code.
+- Snake_case method names are automatically camelized (e.g., `get_by_ean` → `getByEAN/`).
+- `Moloni::Auth` now points to the correct web auth URL (`https://www.moloni.pt/ac/root/oauth/`); previously it built a broken URL from `api.moloni.pt/v1/authorize/`.
+- Auth token refresh updates `config.access_token_expires_at` and `config.refresh_token_expires_at`.
+
+## Testing / lint quirks
+- `.rspec` sets `--order rand`, `--format documentation`, and `--require spec_helper`.
+- RuboCop target is Ruby 3.2 (`.rubocop.yml`). Line length is 100 characters; `spec/**/*` is excluded from line-length checks.
+- `Layout/LineLength` was moved from `Metrics` to `Layout` namespace in newer RuboCop.
+
+## Important model changes (0.5)
+- `Customer#create` and `#update` still inject empty required params.
+- `Tax#iva_normal`, `#iva_intermedio`, `#iva_reduzido` still exist with hardcoded IDs.
+- `Company.all` (the broken GET version) was removed; use `Company.getAll` via dynamic dispatch.
+- `User.me` and `Printer.all` remain as explicit custom methods.

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in moloni.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,140 @@
+PATH
+  remote: .
+  specs:
+    moloni (0.5.0)
+      addressable (~> 2.9)
+      faraday (~> 2.14)
+      launchy (~> 3.1)
+      sinatra (~> 4.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.2)
+    base64 (0.2.0)
+    bigdecimal (4.1.2)
+    byebug (11.1.3)
+    childprocess (5.1.0)
+      logger (~> 1.5)
+    coderay (1.1.3)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    diff-lcs (1.6.2)
+    docile (1.4.0)
+    dotenv (2.8.1)
+    faraday (2.14.1)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.0.2)
+    hashdiff (1.2.1)
+    json (2.7.1)
+    language_server-protocol (3.17.0.3)
+    launchy (3.1.1)
+      addressable (~> 2.8)
+      childprocess (~> 5.0)
+      logger (~> 1.6)
+    logger (1.7.0)
+    method_source (1.0.0)
+    mustermann (3.0.0)
+      ruby2_keywords (~> 0.0.1)
+    parallel (1.24.0)
+    parser (3.3.0.2)
+      ast (~> 2.4.1)
+      racc
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
+    public_suffix (5.0.4)
+    racc (1.7.3)
+    rack (3.2.6)
+    rack-protection (4.2.1)
+      base64 (>= 0.1.0)
+      logger (>= 1.6.0)
+      rack (>= 3.0.0, < 4)
+    rack-session (2.1.2)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rainbow (3.1.1)
+    rake (13.1.0)
+    regexp_parser (2.8.3)
+    rexml (3.2.6)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.59.0)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.2.2.4)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.30.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.30.0)
+      parser (>= 3.2.1.0)
+    rubocop-capybara (2.20.0)
+      rubocop (~> 1.41)
+    rubocop-factory_bot (2.25.0)
+      rubocop (~> 1.33)
+    rubocop-rspec (2.26.1)
+      rubocop (~> 1.40)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    sinatra (4.2.1)
+      logger (>= 1.6.0)
+      mustermann (~> 3.0)
+      rack (>= 3.0.0, < 4)
+      rack-protection (= 4.2.1)
+      rack-session (>= 2.0.0, < 3)
+      tilt (~> 2.0)
+    tilt (2.3.0)
+    unicode-display_width (2.5.0)
+    webmock (3.26.2)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  arm64-darwin-22
+
+DEPENDENCIES
+  bundler (~> 2.4)
+  dotenv (~> 2.8)
+  moloni!
+  pry-byebug (~> 3.10)
+  rake (~> 13.0)
+  rspec (~> 3.13)
+  rubocop (~> 1.59)
+  rubocop-rspec (~> 2.26)
+  simplecov (~> 0.22)
+  webmock (~> 3.26)
+
+BUNDLED WITH
+   2.4.21

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Tiago Pinto
+
+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/MOLONI_API_DOC.md

@@ -0,0 +1,328 @@
+# Moloni API Documentation Summary
+
+> Comprehensive reference for the Moloni API v1, compiled from the official documentation at [moloni.pt/dev](https://www.moloni.pt/dev/). This gem wraps the Portuguese online invoicing platform API.
+
+---
+
+## 1. Overview
+
+- **API Base URL:** `https://api.moloni.pt/v1/`
+- **Protocol:** HTTPS only
+- **Authentication:** OAuth 2.0
+- **Request Method:** **All requests must use `POST`**, including read operations.
+- **Data Format:** JSON (recommended) or `x-www-form-urlencoded`
+- **Official Docs:** [https://www.moloni.pt/dev/](https://www.moloni.pt/dev/)
+
+---
+
+## 2. Authentication (OAuth 2.0)
+
+You need a **Developer ID**, **Redirect URI**, and **Client Secret** obtained from the Moloni developer area.
+
+### 2.1 Web Application Flow (Recommended)
+
+**Step 1 — Redirect user to authorize:**
+
+```
+GET https://www.moloni.pt/ac/root/oauth/
+  ?response_type=code
+  &client_id=<DEVELOPER_ID>
+  &redirect_uri=<REDIRECT_URI>
+```
+
+**Step 2 — User logs in and authorizes.**
+
+Moloni redirects back to your `redirect_uri` with `?code=<AUTHORIZATION_CODE>`.
+
+**Step 3 — Exchange code for tokens:**
+
+```
+GET https://api.moloni.pt/v1/grant/
+  ?grant_type=authorization_code
+  &client_id=<DEVELOPER_ID>
+  &client_secret=<CLIENT_SECRET>
+  &redirect_uri=<REDIRECT_URI>
+  &code=<AUTHORIZATION_CODE>
+```
+
+**Response:**
+```json
+{
+  "access_token": "bad936989865c810e14a81ea9fc2cd8ea8d5e9f6",
+  "expires_in": 3600,
+  "token_type": "bearer",
+  "scope": null,
+  "refresh_token": "96f84474f2ed3ae07e4e1b5d08fe1893d08a204f"
+}
+```
+
+### 2.2 Native / Plugin Flow
+
+For desktop apps or plugins where you collect user credentials directly. **Less secure; avoid persisting passwords.**
+
+```
+GET https://api.moloni.pt/v1/grant/
+  ?grant_type=password
+  &client_id=<DEVELOPER_ID>
+  &client_secret=<CLIENT_SECRET>
+  &username=<USER_USERNAME>
+  &password=<USER_PASSWORD>
+```
+
+### 2.3 Token Refresh
+
+**Access Token:** valid for **1 hour**  
+**Refresh Token:** valid for **14 days**
+
+```
+GET https://api.moloni.pt/v1/grant/
+  ?grant_type=refresh_token
+  &client_id=<DEVELOPER_ID>
+  &client_secret=<CLIENT_SECRET>
+  &refresh_token=<REFRESH_TOKEN>
+```
+
+If the refresh token expires, the user must re-authenticate from scratch.
+
+---
+
+## 3. Making Requests
+
+### 3.1 Required Query String Parameters
+
+Every API request **must** include these in the query string:
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `access_token` | **Yes** | The current OAuth access token. |
+| `json` | No | Set to `true` to send/receive JSON instead of the default `x-www-form-urlencoded`. |
+| `human_errors` | No | Set to `true` to receive verbose, human-readable error messages. |
+
+Example URL:
+```
+https://api.moloni.pt/v1/products/getOne/?access_token=xxx&json=true
+```
+
+### 3.2 POST Body
+
+All other data must be sent in the **body** of the `POST` request.
+
+- **`x-www-form-urlencoded`** (default): `company_id=5&product_id=534521`
+- **`JSON`** (when `json=true`): `{"company_id": 5, "product_id": 534521}`
+
+> **Important:** The official documentation states that **all** requests to the API must be sent via `POST`, including read-only operations like `getOne` and `getAll`.
+
+### 3.3 Ruby Example (using Faraday)
+
+```ruby
+require 'faraday'
+require 'json'
+
+conn = Faraday.new(url: 'https://api.moloni.pt/v1/') do |f|
+  f.request :json
+  f.response :json, parser_options: { symbolize_names: true }
+end
+
+response = conn.post('products/getOne/') do |req|
+  req.params['access_token'] = 'your_access_token'
+  req.params['json'] = 'true'
+  req.body = { company_id: 5, product_id: 534_521 }
+end
+
+puts response.body
+```
+
+---
+
+## 4. Response Format
+
+Successful responses return a JSON object or array. The exact structure depends on the endpoint.
+
+Example (product detail):
+```json
+{
+  "product_id": 534521,
+  "name": "Sample Product",
+  ...
+}
+```
+
+---
+
+## 5. Error Handling
+
+### 5.1 Authentication Errors
+
+HTTP status: **400 Bad Request**
+
+Response body:
+```json
+{
+  "error": "invalid_grant",
+  "error_description": "Token is no longer valid"
+}
+```
+
+Common errors:
+- `invalid_client` — missing or invalid `client_id`
+- `invalid_grant` — expired/invalid token or authorization code
+- `redirect_uri_mismatch` — `redirect_uri` does not match developer settings
+- `unsupported_grant_type` — invalid `grant_type` value
+
+### 5.2 Data Validation Errors
+
+Returned when required fields are missing or malformed.
+
+**Default format:**
+```json
+[
+  "1 name",
+  "3 email",
+  "2 language_id 1 0"
+]
+```
+
+Interpretation: `<error_code> <field_name> [<params>...]`
+
+| Code | Meaning | Params |
+|------|---------|--------|
+| `1` | Field is required | — |
+| `2` | Must be a number (integer if `1`, > `2`, < `3`, etc.) | `1: integer[1|0]; 2: >; 3: <; 4: >=; 5: <=` |
+| `3` | Invalid email | — |
+| `4` | Must be unique | — |
+| `5` | Must be a valid value `[{1}]` | `1: accepted values (JSON)` |
+| `6` | Must be a URL | — |
+| `7` | Must be a valid Portuguese postal code | — |
+| `8` | Must be a valid Portuguese NIF | — |
+| `9` | Must be a date in `YYYY-mm-dd` | — |
+| `10` | Invalid document association | — |
+| `11` | Document cannot be sent to AT | — |
+| `12` | Date must be `{1} {2}` | `1: operator[<|<=|=|>=|>]; 2: other date` |
+| `13` | Must be a valid phone contact | — |
+| `14` | Product has two taxes, one "other" and one VAT, but IVA is before or not cumulative | — |
+| `15` | Product has more than one IVA | — |
+| `16` | Legal requirement: customer must be identified with name, address, and postal code different from "Consumidor Final", "Desconhecido", "0000-000" | — |
+| `17` | Field limit reached | — |
+
+**Verbose format** (with `human_errors=true`):
+```json
+[
+  {
+    "code": "1 name",
+    "description": "Field 'name' is required"
+  },
+  {
+    "code": "3 email",
+    "description": "Field 'email' must be a valid email address"
+  }
+]
+```
+
+---
+
+## 6. API Domain Areas
+
+### 6.1 Global Data
+
+Reference data endpoints (no company-specific state changes):
+
+| Resource | Description |
+|----------|-------------|
+| `countries/` | List all available countries |
+| `fiscalZones/` | List fiscal zones |
+| `languages/` | List available languages |
+| `currencies/` | List available currencies |
+| `documentModels/` | List PDF document models |
+| `taxExemptions/` | VAT exemption codes |
+| `currencyExchange/` | Currency exchange rates |
+| `multibancoGateways/` | Multibanco payment gateways |
+
+Typical methods: `getAll`, `getOne`.
+
+---
+
+### 6.2 Products
+
+Manage products, categories, stock, and pricing.
+
+| Resource | Description |
+|----------|-------------|
+| `products/` | CRUD operations on products/services |
+| `productCategories/` | Manage product/service categories |
+| `productStocks/` | Manage stock movements |
+| `priceClasses/` | Manage price tables (Pro plan only) |
+
+Typical methods: `getAll`, `getOne`, `insert`, `update`, `delete`.
+
+---
+
+### 6.3 Documents
+
+Extensive document management covering sales, purchases, and logistics.
+
+| Resource | Description |
+|----------|-------------|
+| `documents/` | General document operations |
+| `invoices/` | Sales invoices |
+| `receipts/` | Receipts |
+| `creditNotes/` | Credit notes |
+| `debitNotes/` | Debit notes |
+| `simplifiedInvoices/` | Simplified invoices |
+| `deliveryNotes/` | Delivery notes |
+| `billsOfLading/` | Bills of lading |
+| `ownAssetMG/` | OAM Guides |
+| `waybills/` | Waybills |
+| `customerReturnNotes/` | Customer return notes |
+| `estimates/` | Estimates/quotes |
+| `internalDocuments/` | Internal documents |
+| `invoiceReceipts/` | Invoice-receipts |
+| `paymentReturns/` | Payment returns |
+| `purchaseOrders/` | Purchase orders |
+| `supplierPurchaseOrders/` | Supplier purchase orders |
+| `supplierInvoices/` | Supplier invoices |
+| `supplierSimplifiedInvoices/` | Supplier simplified invoices |
+| `supplierCreditNotes/` | Supplier credit notes |
+| `supplierDebitNotes/` | Supplier debit notes |
+| `supplierReturnNotes/` | Supplier return notes |
+| `supplierReceipts/` | Supplier receipts |
+| `supplierWarrantyRequests/` | Supplier warranty requests |
+| `globalGuides/` | Global guides |
+
+Documents are usually created via `insert` and retrieved via `getOne`/`getAll`, passing `company_id` and document identifiers.
+
+---
+
+## 7. Ruby Gem Implementation Notes
+
+### 7.1 What the gem currently does
+
+The existing gem (`lib/moloni.rb`) configures a `Faraday` connection to `https://api.moloni.pt/v1/` and automatically appends `access_token` and `json=true` to every request via query parameters. Models inherit from `Moloni::BaseModel`.
+
+### 7.2 Known discrepancies vs. official API docs
+
+1. **Auth URL mismatch:** The gem's `Moloni::Auth` builds the authorization URL by joining `API_BASE_URL` (`https://api.moloni.pt/v1/`) with `authorize/`. The **official web auth endpoint** is `https://www.moloni.pt/ac/root/oauth/`. The token exchange endpoint (`…/v1/grant/`) is correct.
+
+2. **GET vs POST for read operations:** The gem's `BaseModel.get_path` performs a Faraday `GET`. The official documentation states **all requests must be `POST`**, with data in the request body. Only the grant/token endpoints legitimately use `GET`.
+
+3. **Body encoding:** The gem's `post_path` uses `MultiJson.dump(opts)` (JSON body), which is fine as long as `json=true` is present in the query string. The API defaults to `x-www-form-urlencoded` otherwise.
+
+4. **Token validity tracking:** The gem does not currently implement automatic access-token refresh. You must track `expires_in` (1 hour) and `refresh_token` expiry (14 days) yourself and call `Moloni::Auth.refresh_tokens` before making requests with an expired token.
+
+---
+
+## 8. Quick Reference: Environment Variables
+
+The gem and CLI tools expect these variables (see `.env` in repo root):
+
+| Variable | Purpose |
+|----------|---------|
+| `DEVELOPER_ID` | OAuth `client_id` |
+| `REDIRECT_URI` | OAuth callback URL |
+| `CLIENT_SECRET` | OAuth `client_secret` |
+| `ACCESS_TOKEN` | Short-lived API token (1h) |
+| `REFRESH_TOKEN` | Long-lived refresh token (14 days) |
+| `COMPANY_ID` | Default company for API calls |
+
+---
+
+*Last updated from official Moloni API docs (2026). If the gem behavior diverges from this doc, trust the official docs and open an issue.*