smartbill-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2972838a84f90174e2d1caca6e3dab19b49a8773d0f1610e8b92a2d3cc11f17c
+  data.tar.gz: 8827e1879f9d53a2325593f9c1251db93d1310cba5975b62e60c5dbd83b80c45
+SHA512:
+  metadata.gz: ca3c185e7665607ec61d3ad976be61525e38d3dcb85bc5d05c762d3802296af0c0d251fbb65c191c43b65a9974708282ec16eaac198f25d7a2f64a4741977fa7
+  data.tar.gz: 25490736acc0f2d4ccd3ba1e5a48ff1961ba5acaece48d530afa3a9f45cc5a98271e708f2ca9c1654e4416a1ac1b66cb3187e28c6382bae6f5714d1e99a5d463

data/AGENTS.md

@@ -0,0 +1,211 @@
+# PROJECT KNOWLEDGE BASE
+
+**Generated:** 2026-06-21
+
+## OVERVIEW
+Project: **smartbill-sdk** (gem name `smartbill-sdk`, namespace `Smartbill::Sdk`)
+Stack: Ruby ≥ 3.2, stdlib `Net::HTTP` + `base64` + `json`, models via
+`dry-struct` + `dry-types` + `dry-inflector`, request validation via
+`dry-validation`, autoloading via `zeitwerk`; build via Bundler/gemspec;
+tests with `minitest` + `WebMock`; lint with `RuboCop`.
+
+A Ruby SDK for the [SmartBill Cloud REST API](https://www.facturionline.ro/api-program-facturare/)
+offering a **synchronous** `Smartbill::Sdk::Client` with typed request/response
+models covering every endpoint in the official `openapi.json` spec. It is a
+faithful Ruby port of the Python `smartbill-rest-sdk`
+(see `/home/dnutiu/PycharmProjects/smartbill-sdk`).
+
+## STRUCTURE
+
+Constants under `Smartbill::Sdk` are **autoloaded by Zeitwerk** from
+`lib/smartbill/sdk/`, following the **one file per constant** convention
+(the entry file `lib/smartbill/sdk.rb` sets up a `Zeitwerk::Loader` with
+`push_dir(..., namespace: Smartbill::Sdk)`). No `require_relative` chains —
+constants resolve on first reference. Inflection overrides map `version.rb`
+→ `VERSION` and `api_error.rb` → `APIError`.
+
+```
+lib/smartbill/sdk.rb                  # entry point: Zeitwerk loader setup + DEFAULT_BASE_URL alias
+lib/smartbill/sdk/version.rb          # Smartbill::Sdk::VERSION
+lib/smartbill/sdk/error.rb            # Smartbill::Sdk::Error (base)
+lib/smartbill/sdk/auth_error.rb       # AuthError (HTTP 401)
+lib/smartbill/sdk/rate_limit_error.rb # RateLimitError (HTTP 403)
+lib/smartbill/sdk/transport_error.rb  # TransportError
+lib/smartbill/sdk/validation_error.rb # ValidationError (missing required fields)
+lib/smartbill/sdk/api_error.rb        # APIError (.error_text/.message_field/.status_code)
+lib/smartbill/sdk/response.rb         # Response struct (status/body/content_type)
+lib/smartbill/sdk/net_http_adapter.rb # NetHttpAdapter (default HTTP adapter, Net::HTTP)
+lib/smartbill/sdk/transport.rb        # Transport module: build_auth, build_request, parse_envelope, handle_response + constants
+lib/smartbill/sdk/transport/request.rb        # Transport::Request struct
+lib/smartbill/sdk/transport/rate_limiter.rb   # Transport::RateLimiter
+lib/smartbill/sdk/client.rb           # Client (sync) + services wiring
+lib/smartbill/sdk/types.rb                # Types (Dry::Types) + StrOrInt sum type
+lib/smartbill/sdk/models.rb           # Models namespace + INFLECTOR
+lib/smartbill/sdk/models/struct.rb             # Struct < Dry::Struct: snake_case<->camelCase, to_h, to_attributes, ValidationError translation
+lib/smartbill/sdk/models/document_type.rb     # DocumentType (constants)
+lib/smartbill/sdk/models/payment_type.rb      # PaymentType (constants)
+lib/smartbill/sdk/models/discount_type.rb     # DiscountType (constants)
+lib/smartbill/sdk/models/client.rb            # Client
+lib/smartbill/sdk/models/product.rb           # Product
+lib/smartbill/sdk/models/invoice_ref.rb       # InvoiceRef (series/seriesName alias)
+lib/smartbill/sdk/models/invoice_payment.rb   # InvoicePayment
+lib/smartbill/sdk/models/invoice.rb           # Invoice
+lib/smartbill/sdk/models/storno_request.rb    # StornoRequest
+lib/smartbill/sdk/models/estimate.rb          # Estimate
+lib/smartbill/sdk/models/payment.rb           # Payment
+lib/smartbill/sdk/models/email_document.rb    # EmailDocument
+lib/smartbill/sdk/models/tax.rb               # Tax
+lib/smartbill/sdk/models/series.rb            # Series
+lib/smartbill/sdk/models/taxes_response.rb    # TaxesResponse
+lib/smartbill/sdk/models/series_list_response.rb # SeriesListResponse
+lib/smartbill/sdk/models/stock_product.rb     # StockProduct
+lib/smartbill/sdk/models/stock_warehouse.rb   # StockWarehouse
+lib/smartbill/sdk/models/stock_list.rb        # StockList
+lib/smartbill/sdk/models/stocks_response.rb   # StocksResponse
+lib/smartbill/sdk/models/base_response.rb     # BaseResponse
+lib/smartbill/sdk/models/invoice_create_response.rb
+lib/smartbill/sdk/models/storno_response.rb
+lib/smartbill/sdk/models/payment_status_response.rb
+lib/smartbill/sdk/models/proforma_invoices_response.rb
+lib/smartbill/sdk/models/email_status.rb
+lib/smartbill/sdk/models/email_response.rb
+lib/smartbill/sdk/models/fiscal_receipt_response.rb
+lib/smartbill/sdk/services.rb          # Services namespace + dump_model/parse helpers
+lib/smartbill/sdk/services/base_service.rb        # BaseService
+lib/smartbill/sdk/services/invoices_service.rb    # InvoicesService
+lib/smartbill/sdk/services/estimates_service.rb   # EstimatesService
+lib/smartbill/sdk/services/payments_service.rb    # PaymentsService
+lib/smartbill/sdk/services/email_service.rb       # EmailService
+lib/smartbill/sdk/services/configuration_service.rb # ConfigurationService (taxes + series)
+lib/smartbill/sdk/services/stocks_service.rb      # StocksService
+lib/smartbill/sdk/contracts.rb         # Contracts namespace (dry-validation)
+lib/smartbill/sdk/contracts/base.rb             # Contracts::Base < Dry::Validation::Contract + DATE_REGEX + validate!
+lib/smartbill/sdk/contracts/invoice_contract.rb
+lib/smartbill/sdk/contracts/estimate_contract.rb
+lib/smartbill/sdk/contracts/payment_contract.rb
+lib/smartbill/sdk/contracts/email_contract.rb
+lib/smartbill/sdk/contracts/storno_contract.rb
+lib/smartbill/sdk/contracts/invoice_payment_contract.rb
+lib/smartbill/sdk/contracts/invoice_ref_contract.rb
+test/                             # minitest + WebMock suite (60 tests)
+examples/                         # standalone runnable Ruby scripts
+skills/                           # pi agent skills (SKILL.md per API area)
+sig/smartbill/sdk.rbs             # RBS type signatures for the full public API
+Steepfile                         # opt-in Steep typecheck configuration
+```
+
+## COMMANDS
+| Action              | Command                          |
+|---------------------|----------------------------------|
+| Install (dev)       | `bundle install`                 |
+| Run tests           | `bundle exec rake test`          |
+| Run a single test   | `bundle exec ruby -Ilib:test test/smartbill/test_invoices.rb` |
+| Lint                | `bundle exec rubocop`            |
+| Auto-correct lint   | `bundle exec rubocop -A`         |
+| Build gem           | `bundle exec rake build`         |
+| Console             | `bin/console`                    |
+| Run an example      | `bundle exec ruby examples/create_invoice_sync.rb` |
+| Validate RBS sigs   | `bundle exec rake rbs:validate` |
+| Typecheck (opt-in)  | `bundle exec steep check` (needs dry-rb RBS; see note below) |
+
+## CODING STANDARDS
+*   **Language**: Ruby 3.2+; `# frozen_string_literal: true` everywhere.
+*   **Autoloading**: Zeitwerk, one file per constant. To add a new class
+    `Smartbill::Sdk::Foo::Bar`, create `lib/smartbill/sdk/foo/bar.rb`
+    defining `class Bar` (and a `lib/smartbill/sdk/foo.rb` namespace file
+    `module Foo; end` if the directory is new). Do **not** add
+    `require_relative` for SDK-internal constants — let Zeitwerk resolve
+    them. Only `require` stdlib/gems (`base64`, `json`, `net/http`, `uri`,
+    `zeitwerk`) at the top of files that use them. If a file basename does
+    not camelcase to the desired constant (e.g. `api_error.rb` → `APIError`,
+    `version.rb` → `VERSION`), add an entry to `loader.inflector.inflect`
+    in `lib/smartbill/sdk.rb`.
+*   **Style**: 2-space indent, double-quote strings (enforced by RuboCop).
+*   **Models**: subclass `Smartbill::Sdk::Models::Struct` (a `Dry::Struct`)
+    and declare attributes with the dry-struct `attribute` DSL using types
+    from `Smartbill::Sdk::Types` (e.g. `attribute :company_vat_code,
+    Types::Strict::String`; `attribute :price, Types::Coercible::Float.optional.default(nil)`;
+    `attribute :products, Types::Array.of(Product).default([].freeze)`).
+    The base `Struct` handles: snake_case/camelCase input key normalization
+    (`transform_keys` + `Dry::Inflector`), camelCase output via `#to_h`
+    (nils omitted by default), recursive nested serialization, and
+    `Dry::Struct::Error` → `ValidationError` translation. Mixed string/int
+    fields use `Types::StrOrInt`. Unknown input keys are **ignored** (not
+    preserved) — permissive parsing without re-emission. Use `#to_attributes`
+    for the snake_case hash (with nils, nested structs → hashes) fed to
+    contracts.
+*   **Enums**: plain modules of string/int constants (`PaymentType::CHITANTA`
+    == `"Chitanta"`). Pass the constant; it is stored/serialized as-is.
+*   **Validation**: each request model has a `Smartbill::Sdk::Contracts::*Contract`
+    (`< Contracts::Base < Dry::Validation::Contract`). The contract's `params`
+    block declares only the fields with semantic rules (dates via
+    `DATE_REGEX`, enum membership via `included_in?`, ranges, nested hashes);
+    unknown keys are ignored by dry-validation. Services call
+    `validate(struct, Contracts::XContract)` before sending, which runs
+    `Contract.validate!(struct)` → `contract.new.call(struct.to_attributes)`
+    and raises `ValidationError` with aggregated `path text` messages on
+    failure. To add a rule, edit the contract's `params` block — do **not**
+    re-declare every field, only the ones you validate.
+*   **Services**: each service builds a `Transport::Request` via
+    `Transport.build_request(...)` and parses the response with
+    `Services.parse(payload, ModelClass)`. Services get the client (executor)
+    injected; they call `@client.execute(request, binary: ...)`. Request-taking
+    methods (`invoices.create`, `invoices.reverse`, `estimates.create`,
+    `payments.create`, `email.send`) call `validate(model, Contracts::XContract)`
+    **before** building the request so invalid input never hits the network.
+*   **Errors**: raise `Smartbill::Sdk::Error` subclasses (one per file under
+    `lib/smartbill/sdk/`); never bare `RuntimeError`. `Transport.handle_response`
+    is the single place that maps HTTP status / envelopes to exceptions.
+*   **HTTP adapter**: the client talks to a swappable adapter through one
+    method `#call(req) -> Response`. The default is `NetHttpAdapter`
+    (stdlib `Net::HTTP`). Inject a custom `http:` object in tests/for other
+    backends.
+
+## WHERE TO LOOK
+*   **Source**: `lib/smartbill/sdk/`
+*   **Tests**: `test/` (HTTP mocked via WebMock; `test/test_helper.rb` has
+    shared helpers: `make_client`, `envelope`, `last_request`, `query_of`,
+    `assert_auth`, `assert_json_headers`)
+*   **Docs**: `README.md`, `examples/`
+*   **Public API surface**: `lib/smartbill/sdk.rb` and `Smartbill::Sdk::Client`
+
+## NOTES
+*   **Auth**: HTTP Basic Auth with `username:token` where `username` is the
+    login e-mail and `token` comes from SmartBill Cloud → *Contul Meu →
+    Integrari → API*.
+*   **JSON only**: the SDK sends JSON; XML is not supported.
+*   **Rate limit**: 30 calls / 10 seconds — exceeding it triggers a
+    server-side 403 that blocks access for 10 minutes. Opt into a
+    client-side preemptive limiter with `Client.new(..., enforce_rate_limit: true)`.
+*   **Dates**: all date fields are `YYYY-MM-DD` strings, matching the API.
+*   **Sync only**: there is no async client (Ruby's concurrency model
+    differs from Python's asyncio). For concurrency, run independent
+    requests on separate threads — `Net::HTTP` opens a fresh connection
+    per request so this is safe (see `examples/taxes_and_stocks_sync.rb`).
+*   **`taxes` / `series` alias**: on a `Client`, `client.taxes` and
+    `client.series` are the *same* `ConfigurationService` instance.
+*   **Tests are mocked**: no network calls; WebMock intercepts `Net::HTTP`.
+    The full suite (60 tests) passes offline.
+*   **Runtime dependencies**: `base64` (no longer a default gem in Ruby
+    3.4+), `zeitwerk` (autoloader), `dry-struct` + `dry-types` +
+    `dry-inflector` (models) and `dry-validation` (request contracts). All
+    are declared in the gemspec.
+*   **Port origin**: this codebase was ported from the Python
+    `smartbill-rest-sdk`; behavior, models and endpoint coverage match.
+*   **Agent skills**: `skills/` ships three pi `SKILL.md` files
+    (`smartbill-invoices`, `smartbill-payments`, `smartbill-email`) that
+    teach coding agents how to use the SDK, with Ruby code snippets.
+*   **Type signatures**: `sig/smartbill/sdk.rbs` contains RBS signatures for
+    the entire public API — `Client`, all `Services::*`, all `Models::*`
+    (with read-only `attr_reader` per attribute and nil-able `?` types for
+    optional fields), all `Contracts::*`, the `Transport` module + `Request`/
+    `Response`/`RateLimiter`, `NetHttpAdapter`, and the `Error` hierarchy.
+    `bundle exec rake rbs:validate` checks syntax + consistency (passes
+    clean). `steep check` is configured via the `Steepfile` but cannot fully
+    typecheck the implementation because `dry-struct` / `dry-validation` do
+    not ship RBS signatures (their DSL — `attribute`, `optional`, `required`,
+    `filled`, `params`, ... — reports as `NoMethod`); this is an inherent
+    limitation, not a signature defect. When adding a public class/method,
+    add its signature to `sig/smartbill/sdk.rbs` in the matching namespace
+    section and keep `rake rbs:validate` green.
+*   No other context files (`.cursorrules`, `CLAUDE.md`, etc.) exist.

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+## [Unreleased]
+
+## [1.0.0] - 2026-06-21
+
+Ruby port of the Python `smartbill-rest-sdk` (v1.0.x).
+
+- Synchronous `Smartbill::Sdk::Client` backed by stdlib `Net::HTTP`.
+- Typed request/response models (snake_case Ruby attrs ↔ camelCase JSON)
+  for invoices, proformas (estimates), payments, fiscal receipts, e-mail,
+  taxes, series and stocks.
+- Envelope unwrapping and a full error hierarchy (`Error`, `AuthError`,
+  `RateLimitError`, `APIError`, `TransportError`, `ValidationError`).
+- Optional client-side `RateLimiter` (30 calls / 10s).
+- WebMock-based test suite (60 tests) and runnable examples.
+
+## [0.1.0] - 2026-06-21
+
+- Initial scaffold (bundle gem).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Denis Nutiu
+
+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

@@ -0,0 +1,265 @@
+# smartbill-sdk
+
+A Ruby SDK for the [SmartBill Cloud REST API](https://www.facturionline.ro/api-program-facturare/),
+offering a synchronous client with typed request/response models covering
+every endpoint in the official `openapi.json` spec.
+
+This is a Ruby port of the Python
+[`smartbill-rest-sdk`](https://github.com/dnutiu/Smart-Bill-SDK).
+
+## Features
+
+- Synchronous `Smartbill::Sdk::Client`.
+- Typed request/response models built on **dry-struct** (type coercion,
+  required-attribute presence, snake_case ⇄ camelCase aliasing) with
+  **dry-validation** contracts enforcing semantic rules (date formats,
+  payment-type enum, positive amounts, recipient e-mail shape) before
+  every request is sent.
+- snake_case Ruby attributes aliased to camelCase JSON automatically
+  (`company_vat_code` ↔ `companyVatCode`).
+- Permissive parsing — unknown API fields are ignored, so new fields
+  don't break parsing.
+- Helper exception hierarchy with the API `errorText` surfaced.
+- Optional client-side rate limiter (SmartBill allows 30 calls / 10s,
+  then blocks for 10 minutes).
+- Runtime dependencies: `dry-struct`, `dry-validation`, `dry-types`,
+  `dry-inflector`, `zeitwerk` (autoloading), and the stdlib `base64`
+  gem (uses `Net::HTTP` under the hood).
+
+## Installation
+
+Add to your application's Gemfile:
+
+```ruby
+gem "smartbill-sdk"
+```
+
+Or install manually:
+
+```bash
+gem install smartbill-sdk
+```
+
+From source (development):
+
+```bash
+bundle install
+bundle exec rake test          # run the test suite
+bundle exec rake rubocop       # lint
+bundle exec rake rbs:validate  # validate the RBS type signatures
+```
+
+The gem ships [RBS](https://github.com/ruby/rbs) type signatures in
+`sig/smartbill/sdk.rbs` covering the full public API (client, services,
+models, contracts, transport, exceptions). Opt-in typechecking with
+[Steep](https://github.com/soutaro/steep) is configured via the `Steepfile`,
+though a fully clean `steep check` currently requires RBS signatures for
+`dry-struct` / `dry-validation`, which are not bundled with those gems.
+
+## Authentication
+
+SmartBill uses HTTP Basic Auth with `username:token`:
+
+- `username` — the e-mail you log in with in SmartBill Cloud.
+- `token` — found in SmartBill Cloud > **Contul Meu** > **Integrari** > **API**.
+
+```ruby
+require "smartbill/sdk"
+
+client = Smartbill::Sdk::Client.new(username: "you@example.com", token: "abc123...")
+```
+
+## Quick start
+
+```ruby
+require "smartbill/sdk"
+
+include Smartbill::Sdk
+
+client = Client.new(username: "you@example.com", token: "...")
+
+invoice = Models::Invoice.new(
+  company_vat_code: "RO12345678",
+  client: Models::Client.new(name: "Intelligent IT", vat_code: "RO12345678",
+                             city: "Sibiu", country: "Romania"),
+  series_name: "FCT",
+  is_draft: false,
+  products: [
+    Models::Product.new(name: "Produs 1", measuring_unit_name: "buc", currency: "RON",
+                        quantity: 2, price: 10, is_tax_included: true,
+                        tax_name: "Redusa", tax_percentage: 9)
+  ]
+)
+
+resp = client.invoices.create(invoice)
+puts "Factura emisa: seria #{resp.series}, numarul #{resp.number}"
+```
+
+The client can also be used with a block that closes it automatically:
+
+```ruby
+Client.new(username: "...", token: "...").with_client do |c|
+  c.invoices.create(invoice)
+end
+```
+
+## Services
+
+| Attribute          | Service                  | Covers                                                        |
+|--------------------|--------------------------|---------------------------------------------------------------|
+| `client.invoices`  | `InvoicesService`        | create, delete, reverse (storno), cancel, restore, payment status, PDF |
+| `client.estimates` | `EstimatesService`       | create, delete, cancel, restore, PDF, invoices-status         |
+| `client.payments`  | `PaymentsService`        | create (general / chitanta / bon fiscal), delete, fiscal-receipt text |
+| `client.email`     | `EmailService`           | `POST /document/send`                                         |
+| `client.taxes`     | `ConfigurationService`   | `GET /tax` (taxes), `GET /series` (series)                    |
+| `client.series`    | `ConfigurationService`   | alias of `client.taxes` — same instance                       |
+| `client.stocks`    | `StocksService`          | `GET /stocks`                                                 |
+
+### Lifecycle: storno / cancel / restore / PDF
+
+```ruby
+storno = Models::StornoRequest.new(company_vat_code: cif, series_name: "FCT", number: "0040")
+st = client.invoices.reverse(storno)
+puts st.document_url
+
+client.invoices.cancel(cif, "FCT", "0040")     # PUT /invoice/cancel
+client.invoices.restore(cif, "FCT", "0040")    # PUT /invoice/restore
+
+pdf_bytes = client.invoices.pdf(cif, "FCT", "0040")  # raw binary String
+File.binwrite("factura.pdf", pdf_bytes)
+```
+
+### Taxes, series and stocks
+
+```ruby
+taxes = client.taxes.taxes("RO12345678")
+taxes.taxes.each { |t| puts "#{t.name}: #{t.percentage}%" }
+
+series = client.series.series("RO12345678", type: "f")  # type: f/c/p/i/n
+series.list.each { |s| puts "#{s.name}: #{s.next_number}" }
+
+stocks = client.stocks.get("RO12345678", "2024-05-01", warehouse_name: "Depozit")
+stocks.list.each { |entry| entry.products.each { |p| puts p.product_name } }
+```
+
+### E-mail
+
+`subject` and `body_text` must be Base64-encoded by the caller, as the
+SmartBill API requires.
+
+```ruby
+email = Models::EmailDocument.new(
+  company_vat_code: "RO12345678", series_name: "FCT", number: "0040",
+  type: Models::DocumentType::INVOICE, to: "client@example.ro",
+  subject: Base64.strict_encode64("Factura FCT0040"),
+  body_text: Base64.strict_encode64("Va trimitem Factura FCT0040.")
+)
+resp = client.email.send(email)
+puts resp.status.code, resp.status.message
+```
+
+## Errors
+
+All errors descend from `Smartbill::Sdk::Error`:
+
+- `AuthError` — HTTP 401 (bad username/token/company CIF).
+- `RateLimitError` — HTTP 403 (rate-limited, blocked 10 min).
+- `APIError` — has `.error_text`, `.message_field`, `.status_code`
+  (the API's `errorText` is surfaced in `.error_text`).
+- `TransportError` — network-level failure.
+- `ValidationError` — a model is missing required fields or fails its
+  validation contract (bad date format, unknown payment type, non-positive
+  amount, etc.). Raised before any HTTP call is made.
+
+```ruby
+rescue Smartbill::Sdk::AuthError => e
+  # ...
+rescue Smartbill::Sdk::APIError => e
+  puts e.error_text, e.status_code
+end
+```
+
+## Validation
+
+Request models are checked against a dry-validation contract before being
+sent, so malformed requests raise `ValidationError` locally instead of
+round-tripping to the SmartBill API. The contracts enforce:
+
+- date fields match `YYYY-MM-DD`;
+- `Payment#type` is one of the SmartBill payment types;
+- `EmailDocument#type` is `factura` / `proforma` and recipients look like
+  e-mail addresses;
+- numeric amounts are positive; `precision` is a non-negative integer;
+- nested payment-at-issuance blocks (`Invoice#payment`) are validated too.
+
+You can also run a contract explicitly:
+
+```ruby
+Smartbill::Sdk::Contracts::InvoiceContract.validate!(invoice) # raises ValidationError
+result = Smartbill::Sdk::Contracts::InvoiceContract.new.call(invoice.to_attributes)
+result.success?  # => true / false
+result.errors.to_h  # => { issue_date: ["is in invalid format"] }
+```
+
+## Rate limiting
+
+SmartBill allows 30 calls / 10 seconds; exceeding it triggers a server-side
+403 that blocks access for 10 minutes. Opt into a client-side preemptive
+limiter with `enforce_rate_limit:`:
+
+```ruby
+client = Smartbill::Sdk::Client.new(username: "...", token: "...", enforce_rate_limit: true)
+```
+
+## Notes
+
+- The SDK talks JSON only (`format="json"`); XML is not supported.
+- All date fields use `YYYY-MM-DD` strings, matching the API.
+- Only a synchronous client is provided. For concurrency, run
+  independent requests on separate threads (each `Net::HTTP` request
+  opens its own connection — see `examples/taxes_and_stocks_sync.rb`).
+
+## Examples
+
+Runnable scripts live in [`examples/`](examples/):
+
+| Script                          | Demonstrates                                   |
+|---------------------------------|------------------------------------------------|
+| `create_invoice_sync.rb`        | Issuing an invoice                             |
+| `create_estimate_sync.rb`       | Issuing a proforma + invoices-status           |
+| `create_payment_sync.rb`        | Registering a `Chitanta` payment              |
+| `invoice_lifecycle_sync.rb`     | Storno / cancel / restore / PDF                |
+| `list_series_sync.rb`           | `GET /series`                                  |
+| `send_email_sync.rb`            | `POST /document/send` with Base64             |
+| `fiscal_receipt_sync.rb`        | `Bon fiscal` with mixed cash/card payment      |
+| `taxes_and_stocks_sync.rb`      | Concurrent `GET /tax` + `GET /stocks` via threads |
+
+## Agent skills
+
+This repo ships ready-to-import [pi](https://github.com/earendil-works/pi-coding-agent)
+**skills** under [`skills/`](skills/) that teach coding agents how to use
+the SDK. Each `SKILL.md` is a self-contained, copy-pasteable guide for one
+area of the API:
+
+| Skill                | Covers                                                                  |
+|----------------------|-------------------------------------------------------------------------|
+| `smartbill-invoices` | Invoices & proformas/estimates: create, storno, cancel, restore, PDF, payment status |
+| `smartbill-payments` | Payments & fiscal receipts (`bon fiscal`): `POST /payment`, payment types, mixed cash/card, fiscal-printer text, delete |
+| `smartbill-email`    | Emailing a document (`POST /document/send`): base64 subject/body, invoice/proforma |
+
+See [`skills/README.md`](skills/README.md) for how to import them into a pi
+agent. The runnable scripts in [`examples/`](examples/) accompany these
+skills.
+
+## Disclaimer
+
+This SDK was written by an AI agent (pi) as a Ruby port of the Python
+`smartbill-rest-sdk`, which was itself generated from the official
+`openapi.json` spec. The Ruby port is verified with a suite of 60 mocked
+tests (using WebMock). Please have a human review it before issuing real
+invoices — accountants work hard enough as it is.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+namespace :rbs do
+  desc "Validate the RBS signature files (syntax + consistency)"
+  task :validate do
+    sh "bundle exec rbs validate"
+  end
+end
+
+# `steep check` requires RBS signatures for dry-struct / dry-validation,
+# which are not bundled with those gems; it is therefore opt-in rather than
+# part of the default task. `rbs:validate` covers signature soundness.
+task default: %i[test rubocop]

data/Steepfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+target :lib do
+  signature "sig"
+  check "lib"
+end