vindi-rails 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8d1b710b6837eb3148aa4dd5d5b683c5031a5dbd42d42ecdf3723f6d3643e707
+  data.tar.gz: 22abd03787ace80ad63dcb43d9cbd52862db17b2e69f3b9a6694a29e455b2dda
+SHA512:
+  metadata.gz: 4d28a2ed062ddeb3476448a1e5e87227c4e583181eed44694ed1ceda85a9ef150ebd435b9405324c21e5af777bdd048819a44f62566ed47949d7ca8b4627a19a
+  data.tar.gz: 4326a2c91cfc5c827b3054d81fcf3553fd09ce625dfd977215aedc437554fe3af2eecc17c7f83e3dd6c01e51f7160b0d6df1f2dd5bf61af8c1398de54bc35e19

data/.agents/rules/code-style-ruby.md

@@ -0,0 +1,100 @@
+---
+trigger: manual
+---
+
+# Rails Engineering Guidelines
+## Code Style
+* Functions: 4-20 lines. Split if longer.
+* Files: under 500 lines. Split by responsibility.
+* One thing per function, one responsibility per module (SRP).
+* Names: specific and unique. Avoid `data`, `handler`, `manager`, `service`. Prefer names that describe a business action.
+* No code duplication. Extract shared logic into a function/module.
+* Early returns over nested ifs. Max 2 levels of indentation.
+* Exception messages must include the offending value and expected shape.
+* Prefer immutable data flow when possible.
+* Avoid metaprogramming unless it clearly reduces complexity.
+## Rails Architecture
+* Controllers orchestrate. Business rules belong elsewhere.
+* Controllers should stay under ~30 lines per action.
+* Models own persistence and simple validations.
+* Complex business rules belong in Service Objects.
+* Service Objects should represent actions (`CreateOrder`, `CancelSubscription`, `ImportCustomers`).
+* Avoid generic classes such as `UserService`, `OrderManager`, `PaymentHandler`.
+* Query logic reused more than once belongs in Query Objects.
+* Form Objects should encapsulate complex input validation and transformations.
+* Prefer composition over inheritance.
+## Active Record
+* Keep models focused and small (<300 lines preferred).
+* Avoid Fat Models.
+* Validations belong in models; workflows belong in services.
+* Always evaluate queries for N+1 risks.
+* Use `includes`, `preload`, or `eager_load` when appropriate.
+* Prefer scopes only for simple reusable queries.
+* Avoid `default_scope`.
+* Use database constraints in addition to model validations.
+* Every foreign key should have a database constraint when possible.
+* Every frequently queried column should be reviewed for indexing.
+## Database
+* All migrations must be reversible.
+* Use transactions when modifying multiple entities.
+* Prefer database constraints over application-only guarantees.
+* Avoid loading large datasets into memory.
+* Use `find_each` for batch processing.
+* Use `pluck` when only specific columns are needed.
+* Prefer explicit column selection over loading full records.
+## Background Jobs
+* Jobs orchestrate; business logic lives in services.
+* Jobs should be idempotent.
+* Jobs must be retry-safe.
+* External API calls should happen asynchronously when possible.
+* Long-running work should always be delegated to jobs.
+## Events & Messaging
+* Prefer event-driven communication over direct service coupling.
+* Commands change state.
+* Events communicate state changes.
+* Event names should be business-oriented (`OrderCreated`, `PaymentApproved`).
+* Consumers must be idempotent.
+* Use correlation IDs across services.
+## Callbacks
+* Use callbacks only for simple model concerns.
+* Avoid callbacks for external integrations.
+* Avoid callback chains that hide business flow.
+* Prefer explicit service orchestration over lifecycle callbacks.
+## Testing
+* Tests run with a single command: `<project-specific>`.
+* Every new function gets a test.
+* Bug fixes get a regression test.
+* Tests must be F.I.R.S.T.
+* Prefer request specs for APIs.
+* Test behavior, not implementation details.
+* Do not test private methods directly.
+* Factories should create only required data.
+* Avoid excessive fixture setup.
+## Dependencies
+* Inject dependencies through constructor/parameter, not global state.
+* Wrap third-party libraries behind project-owned interfaces.
+* Never couple business logic directly to framework APIs when abstraction is reasonable.
+* External integrations should be replaceable through adapters.
+## Structure
+* Follow Rails conventions before introducing custom patterns.
+* Prefer small focused modules over god files.
+* Predictable paths and responsibilities.
+* Services, Queries, Policies, Forms and Jobs should each have a clear responsibility.
+* Keep domain logic close to the domain it belongs to.
+## Performance
+* Every new query should be reviewed for N+1 issues.
+* Monitor slow queries.
+* Avoid unnecessary object allocations.
+* Cache only after measuring.
+* Prefer database operations over Ruby loops for large datasets.
+* Measure before optimizing.
+## Logging & Observability
+* Structured JSON logging for systems and integrations.
+* Include request ID and correlation ID.
+* Log business events, not only technical failures.
+* External calls must log duration, status and failures.
+* Use metrics and tracing for critical flows.
+* Never log secrets, tokens, credentials or personal data.
+## Formatting
+* Use the language default formatter (`rubocop -A`).
+* Do not debate formatting in code reviews unless readability or correctness is affected.

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+---
+
+## [0.2.0] - 2026-06-10
+
+### Added
+- **Rails Generator**: Added `rails generate vindi:install` command to easily bootstrap the initializer configuration.
+
+---
+
+## [0.1.0] - 2026-06-10
+
+### Added
+- **Core SDK**: Initial release of the Vindi Rails SDK using `RestClient` as the default adapter.
+- **Resources**: Map all 28 API resources, with complete CRUD operations and Minitest coverage implemented for all of them, including core billing, catalog (plans/products), billing/transactions, and administration/batch endpoints.
+- **Dockerization**: Dockerfile and docker-compose.yml configuration to run the test suite isolated.
+- **Testing**: Test suite using Minitest and WebMock (23 test runs, 44 assertions).
+- **Documentation**: Detailed bilingual WIKI (EN / PT-BR) and README configuration/usage guides.

data/CHANGELOG.pt-BR.md

@@ -0,0 +1,21 @@
+# Histórico de Alterações
+
+Todas as alterações notáveis neste projeto serão documentadas neste arquivo.
+
+---
+
+## [0.2.0] - 10-06-2026
+
+### Adicionado
+- **Gerador Rails**: Adicionado o comando `rails generate vindi:install` para inicializar facilmente as configurações de chaves.
+
+---
+
+## [0.1.0] - 10-06-2026
+
+### Adicionado
+- **Core SDK**: Versão inicial do SDK Rails da Vindi utilizando `RestClient` como adaptador HTTP padrão.
+- **Recursos**: Mapeamento de todos os 28 recursos da API, com operações CRUD completas e cobertura Minitest implementada para todos eles, incluindo faturamento core, catálogo (planos/produtos), cobranças/transações, e lotes/administração.
+- **Dockerização**: Configuração do Dockerfile e docker-compose.yml para rodar a suíte de testes de forma isolada.
+- **Testes**: Suíte de testes unitários utilizando Minitest e WebMock (23 execuções de teste, 44 asserções).
+- **Documentação**: Guias detalhados de configuração e uso na WIKI (EN / PT-BR) e README bilíngue.

data/README.md

@@ -0,0 +1,74 @@
+# Vindi Rails SDK
+
+[Leia em Português (README.pt-BR.md)](./README.pt-BR.md)
+
+Ruby/Rails integration SDK for the Vindi API v1 (recurring billing platform).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'vindi-rails', path: 'c:/Users/User/develop/estudo/vindi-rails'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Configuration
+
+Configure the SDK. In a Rails application, you can run the installation generator to create the initializer template:
+
+```bash
+$ rails generate vindi:install
+```
+
+This will create `config/initializers/vindi.rb` where you can set your keys:
+
+```ruby
+Vindi.configure do |config|
+  config.api_key = 'your_private_api_key'
+  # Optional: Define base URL (default is Sandbox)
+  # config.api_url = 'https://gp.vindi.com.br/api/v1'
+end
+```
+
+## Usage
+
+Resources are mapped directly under the `Vindi` namespace.
+
+### Customers
+
+```ruby
+# List customers
+customers = Vindi::Customer.list(page: 1, per_page: 20)
+
+# Create a customer
+customer = Vindi::Customer.create(
+  name: 'John Doe',
+  email: 'john.doe@example.com',
+  registry_code: '12345678909' # CPF/CNPJ
+)
+
+# Update a customer
+Vindi::Customer.update(customer.id, name: 'John Doe Updated')
+
+# Delete a customer
+Vindi::Customer.delete(customer.id)
+```
+
+## Running Tests with Docker Compose
+
+To build and run the Minitest test suite inside Docker:
+
+```bash
+docker compose build
+docker compose run --rm test
+```
+
+## Detailed Documentation
+
+For a full list of mapped resources and detailed usage instructions, check out the [WIKI.md](./WIKI.md).

data/README.pt-BR.md

@@ -0,0 +1,74 @@
+# Vindi Rails SDK
+
+[Read in English (README.md)](./README.md)
+
+SDK de integração Ruby/Rails para a API v1 da Vindi (plataforma de cobranças recorrentes).
+
+## Instalação
+
+Adicione esta linha ao Gemfile da sua aplicação:
+
+```ruby
+gem 'vindi-rails', path: 'c:/Users/User/develop/estudo/vindi-rails'
+```
+
+E então execute:
+
+```bash
+$ bundle install
+```
+
+## Configuração
+
+Configure o SDK. Em aplicações Rails, você pode rodar o gerador de instalação para criar o template de inicializador:
+
+```bash
+$ rails generate vindi:install
+```
+
+Isso criará o arquivo `config/initializers/vindi.rb` onde você poderá configurar suas chaves:
+
+```ruby
+Vindi.configure do |config|
+  config.api_key = 'sua_chave_privada_da_api'
+  # Opcional: Define a URL base (padrão é o Sandbox da Vindi)
+  # config.api_url = 'https://gp.vindi.com.br/api/v1'
+end
+```
+
+## Utilização
+
+Os recursos são mapeados diretamente sob o namespace `Vindi`.
+
+### Clientes
+
+```ruby
+# Listar clientes
+clientes = Vindi::Customer.list(page: 1, per_page: 20)
+
+# Criar cliente
+cliente = Vindi::Customer.create(
+  name: 'João Silva',
+  email: 'joao.silva@exemplo.com',
+  registry_code: '12345678909' # CPF/CNPJ
+)
+
+# Atualizar cliente
+Vindi::Customer.update(cliente.id, name: 'João Silva Alterado')
+
+# Excluir cliente
+Vindi::Customer.delete(cliente.id)
+```
+
+## Rodando os Testes com Docker Compose
+
+Para construir e executar a suíte de testes Minitest dentro do Docker:
+
+```bash
+docker compose build
+docker compose run --rm test
+```
+
+## Documentação Detalhada
+
+Para ver a lista completa de recursos mapeados e instruções de uso detalhadas, confira a [WIKI.pt-BR.md](./WIKI.pt-BR.md).

data/WIKI.md

@@ -0,0 +1,246 @@
+# Vindi SDK Wiki
+
+[Leia em Português (WIKI.pt-BR.md)](./WIKI.pt-BR.md)
+
+Welcome to the `vindi-rails` SDK Wiki. This document details all the mapped resources, operations, and advanced usage guidelines.
+
+---
+
+## 1. SDK Design & Architecture
+
+The SDK uses `RestClient` internally to communicate with the Vindi API.
+Resources are represented as Ruby objects inheriting from `Vindi::Resource`. Attributes returned from the API are accessible via dot-notation methods on the instances.
+
+### Error Handling
+
+The SDK raises specific error classes based on HTTP status codes. All errors inherit from `Vindi::Error`:
+
+- `Vindi::UnauthorizedError` (401)
+- `Vindi::ForbiddenError` (403)
+- `Vindi::NotFoundError` (404)
+- `Vindi::UnprocessableEntityError` (422)
+- `Vindi::RateLimitError` (429)
+- `Vindi::InternalServerError` (500+)
+- `Vindi::APIError` (Fallback for other HTTP statuses)
+
+---
+
+## 2. Resource Mapping & CRUD Capabilities
+
+The table below lists all mapped resources and their operations:
+
+| Resource Class | Endpoint | CRUD Operations Enabled |
+| :--- | :--- | :--- |
+| `Vindi::Customer` | `customers` | `list`, `create`, `update`, `delete` |
+| `Vindi::PaymentProfile` | `payment_profiles` | `list`, `create`, `delete` |
+| `Vindi::Subscription` | `subscriptions` | `list`, `create`, `update`, `delete` |
+| `Vindi::Charge` | `charges` | `list`, `create`, `update` |
+| `Vindi::Plan` | `plans` | `list`, `create`, `update`, `delete` |
+| `Vindi::Product` | `products` | `list`, `create`, `update`, `delete` |
+| `Vindi::ProductItem` | `product_items` | `list`, `create`, `update`, `delete` |
+| `Vindi::Discount` | `discounts` | `list`, `create`, `delete` |
+| `Vindi::Bill` | `bills` | `list`, `create`, `update`, `delete` |
+| `Vindi::BillItem` | `bill_items` | `list` |
+| `Vindi::Period` | `periods` | `list` |
+| `Vindi::Transaction` | `transactions` | `list`, `create` |
+| `Vindi::Usage` | `usages` | `list`, `create`, `delete` |
+| `Vindi::Invoice` | `invoices` | `list` |
+| `Vindi::Movement` | `movements` | `list` |
+| `Vindi::Message` | `messages` | `list` |
+| `Vindi::ExportBatch` | `export_batches` | `list`, `create` |
+| `Vindi::ImportBatch` | `import_batches` | `list`, `create` |
+| `Vindi::Issue` | `issues` | `list`, `update` |
+| `Vindi::Notification` | `notifications` | `list` |
+| `Vindi::Merchant` | `merchants` | `list` |
+| `Vindi::MerchantUser` | `merchant_users` | `list` |
+| `Vindi::Role` | `roles` | `list` |
+| `Vindi::User` | `users` | `list` |
+| `Vindi::Public` | `public` | None (Static Config) |
+| `Vindi::Affiliate` | `affiliates` | `list` |
+| `Vindi::Partner` | `partner` | `list` |
+
+---
+
+## 3. Usage Examples
+
+### Customers (`Vindi::Customer`)
+
+```ruby
+# Create a customer
+customer = Vindi::Customer.create(
+  name: "John Doe",
+  email: "john@example.com"
+)
+
+# Fetch attribute
+puts customer.id
+puts customer.name
+
+# Update customer
+updated = Vindi::Customer.update(customer.id, email: "john.new@example.com")
+
+# Delete customer
+Vindi::Customer.delete(customer.id)
+```
+
+### Payment Profiles (`Vindi::PaymentProfile`)
+
+```ruby
+# Create a card payment profile
+profile = Vindi::PaymentProfile.create(
+  customer_id: 12345,
+  payment_company_code: "visa",
+  holder_name: "JOHN DOE",
+  card_number: "4111111111111111",
+  card_expiration_date: "12/2030",
+  card_cvv: "123"
+)
+
+# Delete payment profile
+Vindi::PaymentProfile.delete(profile.id)
+```
+
+### Subscriptions (`Vindi::Subscription`)
+
+```ruby
+# Create subscription
+subscription = Vindi::Subscription.create(
+  customer_id: customer.id,
+  plan_id: plan.id,
+  payment_method_code: "credit_card"
+)
+
+# Cancel/Delete subscription
+Vindi::Subscription.delete(subscription.id)
+```
+
+### Charges (`Vindi::Charge`)
+
+```ruby
+# List charges
+charges = Vindi::Charge.list(status: "pending")
+
+# Charge details
+puts charges.first.amount
+```
+
+### Plans (`Vindi::Plan`)
+
+```ruby
+# Create a plan
+plan = Vindi::Plan.create(
+  name: "Premium Gold Plan",
+  code: "gold_premium",
+  interval: "months",
+  interval_count: 1
+)
+
+# List plans
+plans = Vindi::Plan.list
+```
+
+### Products & Product Items (`Vindi::Product` & `Vindi::ProductItem`)
+
+```ruby
+# Create a product
+product = Vindi::Product.create(
+  name: "Hosting Service",
+  code: "hosting"
+)
+
+# Associate a product to a plan/subscription
+product_item = Vindi::ProductItem.create(
+  product_id: product.id,
+  plan_id: plan.id
+)
+```
+
+### Discounts (`Vindi::Discount`)
+
+```ruby
+# Create/apply a discount
+discount = Vindi::Discount.create(
+  amount: 15.00,
+  discount_type: "percentage",
+  percentage: 10
+)
+```
+
+### Bills & Bill Items (`Vindi::Bill` & `Vindi::BillItem`)
+
+```ruby
+# Create a bill manually
+bill = Vindi::Bill.create(
+  customer_id: customer.id,
+  payment_method_code: "credit_card",
+  bill_items: [
+    { product_id: product.id, amount: 99.90 }
+  ]
+)
+
+# List bill items
+items = Vindi::BillItem.list(bill_id: bill.id)
+```
+
+### Periods (`Vindi::Period`)
+
+```ruby
+# List subscription periods
+periods = Vindi::Period.list(subscription_id: subscription.id)
+```
+
+### Transactions (`Vindi::Transaction`)
+
+```ruby
+# Create a manual transaction/charge capture
+transaction = Vindi::Transaction.create(
+  charge_id: charge.id,
+  amount: 99.90
+)
+
+# List transactions
+transactions = Vindi::Transaction.list
+```
+
+### Usages (`Vindi::Usage`)
+
+```ruby
+# Report a metered usage for a subscription
+usage = Vindi::Usage.create(
+  subscription_id: subscription.id,
+  quantity: 50,
+  description: "API Calls consumed"
+)
+
+# List usages
+usages = Vindi::Usage.list(subscription_id: subscription.id)
+```
+
+### Invoices (`Vindi::Invoice`)
+
+```ruby
+# List invoices
+invoices = Vindi::Invoice.list(status: "issued")
+```
+
+### Issues (`Vindi::Issue`)
+
+```ruby
+# Update an issue status (e.g. resolve a billing conflict)
+issue = Vindi::Issue.update(issue_id, status: "resolved")
+```
+
+### Import/Export Batches (`Vindi::ImportBatch` & `Vindi::ExportBatch`)
+
+```ruby
+# Start a new customer/subscription import batch
+import_batch = Vindi::ImportBatch.create(
+  batch_type: "customer",
+  file_url: "https://example.com/import.csv"
+)
+
+# Request a data export batch
+export_batch = Vindi::ExportBatch.create(
+  batch_type: "bill"
+)
+```