garu 0.7.0

Dart/Flutter SDK for the Garu payment gateway — PIX, credit card, boleto, recurring charges, webhooks.

0.7.0

Added

• garu.installmentPlans — boleto parcelado (carnê). One product sold as N monthly bank slips. This is seller-financed consumer credit, not a card instalment: nobody guarantees a boleto, so a buyer who stops at parcela 4 leaves the seller with four parcelas and no advance from anyone. Only the first slip exists at creation; the rest are emitted month by month and the sale activates when parcela 1 compensates.

  • create, list, get, reissueInstallment, postponeInstallment, markInstallmentPaid, cancel, requestRefund.
  • create always sends X-Idempotency-Key. It matters more here than anywhere else in the API: the call registers a real boleto, so a blind retry hands one buyer two payable barcodes.
  • CreateInstallmentPlanParams.affiliateId is fixed at sale time — every later parcela inherits it, so omitting it pays that affiliate nothing for the whole carnê.
  • Installment.isPayable is false until a slip is actually registered, so a future parcela is never rendered to a buyer as an empty barcode.
  • InstallmentPlan.remainingScheduled clamps at zero: multa and mora can push totalCollected above totalScheduled, and naive subtraction would report a negative debt.

• garu.refundRequests — refunds Garu cannot make for you. A boleto cannot be reversed and Celcoin exposes no Pix devolução, so the funds already settled to the seller and the return is a bank transfer only they can make. list, get, confirm, reject. Confirming records that the seller asserts the money went back; Garu never observes the transfer.

• V1List<T> for the /api/v1 list envelope, which is flat (data/count/totalCount/totalPages) rather than nesting under meta.

0.6.0

Makes the products resource read-write. Tracks @garuhq/node@0.15.0. Additive — existing read-only callers (list / get / portalConfig) are unchanged.

Added:

• products.create(CreateProductParams) — POST /api/products (gateway returns 201), parses back a typed Product. name is required; value (centavos), description, image, tags, pix, boleto, creditCard, pixAutomatic, installments, isSubscription, subscriptionType, unitLabel, returnUrl, returnUrlButtonText, statementDescriptor are optional. Null fields are omitted from the wire body. Auto-attaches X-Idempotency-Key (UUIDv4) unless CreateProductParams.idempotencyKey is supplied — sent as a header, never in the body — so the runner's transient-failure retries can't double-create a product (matches scheduledCharges.create).
• products.update(Object id, UpdateProductParams) — PATCH /api/products/{id}. id accepts the numeric id (int) or the product UUID (String) — mirroring @garuhq/node's string | number signature — interpolated through Uri.encodeComponent for the same path-injection hardening the rest of the SDK uses. All UpdateProductParams fields are optional and only the ones you set are sent, so updates stay partial.
• CreateProductParams / UpdateProductParams exported from package:garu/garu.dart. Field names are camelCase on the wire, verified against @garuhq/node@0.15.0's CreateProductParams / UpdateProductParams.

Validated:

• dart analyze clean.
• 56 unit tests passing (8 new) in a new products_test.dart — covers the create POST + 201 parse, the auto-generated and caller-supplied X-Idempotency-Key (key omitted from the body), null-field omission, update PATCH with numeric and UUID ids, partial-body merge semantics, and id URL-encoding against a MockClient.

0.5.0

Surfaces Pix Automático — Brazil's BACEN auto-debit recurring Pix — across the SDK. Tracks Garu backend v0.13.0 + v0.14.0. Every change is additive: existing Card/Pix/Boleto callers need no changes.

Pix Automático lets a customer authorize a recurring debit once (a consent link / QR in their bank app); subsequent cycles debit silently with no card on file.

Added:

• PaymentMethod enum (pix / boleto / card / pixAutomatic, plus a forward-compatible unknown sentinel). Each value exposes its API wireValue (PaymentMethod.pixAutomatic.wireValue == 'pix_automatic') and a fromWire parser that resolves unrecognized future values to unknown instead of throwing. Exported from package:garu/garu.dart.
• Charge.method — a typed, forward-compatible PaymentMethod view over the raw Charge.paymentMethod string. Branch on this on transaction.* webhooks to tell a Pix Automático debit apart from a card charge (no new event names — Pix Automático fires the same subscription.* / transaction.payment.* events as card).
• Product.pixAutomatic (non-nullable bool, defaults false) — whether the public checkout exposes Pix Automático for the product. Read from Product.fromJson.
• scheduledCharges.create now accepts 'pix_automatic' in methods. A debug-mode assert in create() enforces the gateway's constraint — 'pix_automatic' requires type: 'recurring' and a productId — and is compiled out of release/AOT builds; the gateway is authoritative and rejects violations with 400 / 404 / 409.

Docs:

• README gains a "Pix Automático" recipe (create a recurring auto-debit series, branch webhooks on Charge.method, failure/cancellation model) and refreshed version/status to 0.5.0.

Build:

• Dependency constraints use caret ranges (http ^1.2.2, crypto ^3.0.5, uuid ^4.5.1, test ^1.25.8, lints ^4.0.0) — the pub.dev convention for libraries, so downstream consumers can resolve alongside other packages. Exact resolved versions are captured in pubspec.lock.

Validated:

• dart analyze clean.
• 49 unit tests passing (11 new) — covers PaymentMethod.fromWire (known values, pix_automatic wire value, unknown fallback), Charge.method resolution, Product.pixAutomatic parse + default, the recurring pix_automatic create round-trip, and the type/productId assertions in create().

0.4.0

Adds immediate dispatch for scheduled charges and per-series recovery windows. Both changes are additive — no breaking changes.

Added:

• scheduledCharges.chargeNow(String id) — dispatch a cycle's charge + customer notification immediately instead of waiting for the due date (the same path the daily billing cron runs). Idempotent: an already-dispatched cycle reports alreadySent and is never re-charged, so the call is safe to retry. Returns a typed ChargeNowResult { outcome, cycleNumber, reason, message }.
• ChargeNowOutcome enum — dispatched / alreadySent / notSent / failed, plus a forward-compatible unknown sentinel. notSent/failed carry a reason (no_email, lock_lost, no_saved_payment_method; card_expired, payment_method_missing, customer_missing, or a raw gateway code).
• CreateScheduledChargeParams.maxRecoveryDays (int?, 1–365) — how long the gateway keeps recovering a missed cycle before giving up. Omit for the system default (14). The 1–365 range is checked by a debug-mode assert (compiled out of release/AOT builds); the gateway is the authoritative boundary and rejects out-of-range values with a 400.
• ScheduledChargeRecord.maxRecoveryDays (int?) on the returned object, with fromJson/toJson support.

Security:

• Every scheduledCharges per-id endpoint now interpolates the id through Uri.encodeComponent(id), extending the v0.3.0 path-injection hardening (previously applied only to products.portalConfig) to the whole resource. An id containing /, ?, or # can no longer spawn extra path segments or leak a query/fragment into the constructed URL.

Validated:

• dart analyze clean.
• 38 unit tests passing (16 new) across models_test.dart and a new scheduled_charges_test.dart — covers chargeNow HTTP wiring (POST, /charge-now path, empty body) against a MockClient, id URL-encoding, all four outcomes + the unknown fallback, the maxRecoveryDays range assertion, and ScheduledChargeRecord round-tripping.

0.3.0

Tracks Garu backend v0.10.0. Per-product portal-config endpoints now accept the product UUID in addition to the legacy numeric id.

Breaking:

• products.portalConfig.{get,set,patch,clear} signature changed from int productId to String productId. Pass the product UUID (preferred — same identifier returned by products.list() and webhook payloads) or convert legacy integer ids with '$id'.
• ProductPortalConfig.productId field type changed from int to String for symmetry with the request signature — round-tripping a returned productId no longer requires manual conversion.

Security:

• URL path interpolation now goes through Uri.encodeComponent(productId) to prevent query/fragment-segment injection (?, #, / in productId would otherwise corrupt the constructed URL).

Why: integer ids are sequential and enumerable. UUIDs are the public-facing identifier across the rest of the API; this brings portal-config in line.

0.2.0

Full feature parity with @garuhq/node@0.8.0. Public API still pre-1.0 — breaking changes possible until v1.0.0, but the surface is now complete enough for production integrations.

Added:

• customers resource (CRUD + setBillingEmailOverride)
• products resource (list, get) + products.portalConfig.{get,set,patch,clear} (B2B2C primitive)
• scheduledCharges resource — full lifecycle: create, list, get, markPaid, postpone, pause, resume, cancelRecurrence, cancelAtPeriodEnd, changePaymentMethod, clearPaymentMethod, listAttempts (per-attempt billing audit, SPEC §4.2)
• meta resource (discover supported payment methods + webhook events)
• Strongly-typed models: Charge, Customer, Product, ProductPortalConfig, SetProductPortalConfigParams, ScheduledChargeRecord, ScheduledChargeAttempt, PaginatedList<T>, PaginationMeta
• GaruFailureCode enum — 10 canonical values + isPermanent helper for routing recurring billing failures
• ScheduledChargeAttemptSource and ScheduledChargeAttemptStatus enums with forward-compatible fromWire parsers (unrecognized values resolve to .unknown instead of throwing)

Validated:

• dart analyze clean (Dart 3.11.5)
• 22 unit tests passing across webhooks_test.dart, models_test.dart, errors_test.dart — covers signature verification (5 cases including tamper detection + replay window), error mapping by HTTP status, and JSON parsing for the v0.8.0 surfaces

Still TODO before v1.0.0:

• Strongly-typed event-timeline models for scheduledCharges.get detail bundle
• Card tokenization helpers (today: pass raw card to charges.create)
• Multi-status filter for scheduledCharges.list (currently passes first only)
• Example Flutter app

0.1.0 (alpha)

Initial scaffold with Garu client, error hierarchy, charges resource, and webhook signature verification. NOT at parity with @garuhq/node.