@adonis-agora/payments 0.16.2 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @adonis-agora/payments
 
+## 0.18.0
+
+### Minor Changes
+
+- [#142](https://github.com/DavideCarvalho/adonis-agora-payments/pull/142) [`6dfa41b`](https://github.com/DavideCarvalho/adonis-agora-payments/commit/6dfa41b887fa646e232523e1e1229395c8677152) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Meter usage against an application resource, read it back against a quota, and type free-plan subscriptions honestly.
+  
+  - `billing_usage_events` gains `scope_type` / `scope_id` and an index on `(scope_type, scope_id, meter)`. `recordUsage` and `usageReport` take `scope: { type, id }` — a project, a workspace, a site — alongside `subscriptionId` / `customerId`, so per-resource usage no longer has to live in `metadata`. Added through the existing `createBillingTables()` upgrade path: an existing install picks the columns up on the next boot (or the next run of the published migration), no new migration to publish. Existing rows read as unscoped.
+  - `payments.usage()` — `record`, `total`, `remaining` and `period` — plus the standalone `usageTotal`, `usageRemaining` and `usagePeriodFor`. `period: { subscription }` derives the window from the subscription's billing cycle: the stored current period when it is current, otherwise stepped by `cycle` from its anchor, so a free row nothing renews still resets every cycle.
+  - `advancePeriodBy(from, cycle, count)` — anchored multi-cycle arithmetic, without the drift chained clamps accumulate.
+  - **Source-breaking:** `SubscriptionRow.gatewayId` (the `withSubscription()` mixin) widens to `string | null`, matching `BillingSubscription` and the column, which was always nullable. Free plans, local trials and comped subscriptions have no gateway subscription to point at. Code assigning `row.gatewayId` into a `string` needs a null check.
+  - `LucidBillingStore.usageReport` now applies `customerId` together with `subscriptionId` instead of dropping it, matching `InMemoryBillingStore`.
+
+## 0.17.0
+
+### Minor Changes
+
+- [#125](https://github.com/DavideCarvalho/adonis-agora-payments/pull/125) [`d55ca3b`](https://github.com/DavideCarvalho/adonis-agora-payments/commit/d55ca3bf16bb6630b6510e758b300d3ec8a561eb) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - **Asaas NFS-e provider fixed** (`invoice.asaas()`); it could not schedule a valid note before.
+  
+  - **Recipient:** sends the Asaas charge as `payment` (when the charge went through Asaas) or the Asaas customer id as `customer` (new `customer.gatewayId`, `cus_…`). It used to send the CPF/CNPJ in `customer`, which Asaas rejects. With neither id, `emit` throws.
+  - **Required fields:** sends `effectiveDate` (default: today in Brasília), `deductions` (default 0), `observations` and the full `taxes` object (`retainIss`, `iss`, `pis`, `cofins`, `csll`, `inss`, `ir`, plus `nbsCode` and any other key given). Retentions default to none; a missing `tax.iss` throws instead of being sent as 0. `municipalServiceId` / `municipalServiceName` are new optional `service` fields; `cityServiceCode` (or `code`) goes as `municipalServiceCode`. The non-existent `serviceCode` is no longer sent.
+  - **No more customer data in free text:** the customer's name and e-mail no longer go into `description`/`notes`, and `metadata` no longer goes into `observations`. `serviceDescription` and `observations` carry what you passed.
+  - **Idempotency:** new `externalReference`; with it, `emit` returns the live note (not cancelled, not `ERROR`) already under that reference instead of scheduling a second one.
+  - **Response mapping** follows the documented `InvoiceGetResponseDTO`: `number`, `pdfUrl`, and the statuses `SCHEDULED`/`SYNCHRONIZED` → `pending`, `AUTHORIZED`/`PROCESSING_CANCELLATION`/`CANCELLATION_DENIED` → `issued`, `CANCELED` → `canceled`, `ERROR` → `failed`.
+  - **Webhooks:** the Asaas payments driver maps `INVOICE_*` to `nfse.created|updated|synchronized|authorized|failed|cancellation_processing|canceled|cancellation_denied`, with the note on `event.data` (`gatewayId`, `status`, `providerStatus`, `number`, `pdfUrl`, `xmlUrl`, `paymentId`, `customerId`, `externalReference`, `statusDescription`…).
+  
+  **Contract:** `InvoiceProvider` gains `cancel(invoiceId, options?: { reason?, providerOnly? })` (Asaas: `POST /invoices/{id}/cancel`, `providerOnly` = `cancelOnlyOnAsaas`; the other built-in providers throw "not supported"). A custom `InvoiceProvider` must add the method. `InvoiceEmitInput` and `InvoiceOptions` gain the optional `effectiveDate`, `deductions`, `observations`, `externalReference`, `customer.gatewayId`, `service.municipalServiceId` and `service.municipalServiceName`; `tax` is now typed as `InvoiceTaxes` (still open to other keys).
+
 ## 0.16.2
 
 ### Patch Changes