@adonis-agora/payments 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @adonis-agora/payments
 
+## 0.13.0
+
+### Minor Changes
+
+- [#55](https://github.com/DavideCarvalho/adonis-agora-payments/pull/55) [`a9b6177`](https://github.com/DavideCarvalho/adonis-agora-payments/commit/a9b61779c12eb9faa264b30947fbdb91d62b11e0) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Three gaps found wiring a real B2B subscription in `gateway` mode.
+  
+  **`externalReference` now survives on subscriptions.** `CreateSubscriptionInput.externalReference` is documented as the id webhook handlers route on, and the column already existed — but `saveSubscription` had no field for it, `SubscriptionListItem` did not expose it and `listSubscriptions` could not filter by it. So the app could send the id, watch the gateway echo it onto every charge, query payments by it, and still have no way to ask "which subscription belongs to this customer of mine?". Added to the store contract, to the returned item and to a new `SubscriptionListQuery`. Related: gateway-mode `SubscriptionsApi.create()` never persisted a subscription row at all, leaving the record to appear only if and when a webhook arrived; it now writes one at creation.
+  
+  **`arrears(store, { externalReference })`.** `renewalFailureCount` and friends are filled by this library's renewal pass, which only runs for `managed` subscriptions — in `gateway` mode (the default) the gateway retries and those fields stay null forever. Answering "is this customer behind, and since when?" meant walking `billing_payments` by hand in every app. The helper does it once, including the non-obvious part: the arrears are dated from the START of the current failure run, because dunning retries the same bill for days and dating from the newest attempt keeps resetting the clock on the customer who is furthest behind.
+  
+  **A provider slot may now be `undefined`, and is skipped.** Every declared provider was built during boot and drivers validate credentials in their constructor, so `payments.asaas({ apiKey: env.get('ASAAS_API_KEY') })` without a key did not disable payments — it stopped the process from starting, which hits CI and every developer machine. `payments.when(condition, () => payments.asaas({ apiKey }))` defers the construction and leaves the slot out. A provider that IS declared and throws still fails the boot, and `ASAAS_WEBHOOK_TOKEN` still refuses to boot on purpose: a missing API key means "cannot charge", a missing webhook token means a public route that marks invoices paid for anyone who posts to it.
+
+## 0.12.0
+
+### Minor Changes
+
+- [#43](https://github.com/DavideCarvalho/adonis-agora-payments/pull/43) [`ea598e8`](https://github.com/DavideCarvalho/adonis-agora-payments/commit/ea598e840aa85e4b2634863165da6bd4fcde90f8) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Pagination is now `{ page, size }` everywhere, matching `@adonis-agora/filter`.
+  
+  **Breaking rename.** Every list read took `{ limit?, offset? }` with a **0-based** `offset`; it now
+  takes `{ page?, size? }` with a **1-based** `page` (default `1`) and `size` as the page size
+  (default 50, capped at 200 — the same numbers as before). The 0-based SQL offset became an internal
+  detail computed by the store, so it can no longer leak into a public type or a query string.
+  
+  The reason is ecosystem consistency, not taste: `@adonis-agora/filter` exposes `FilterInput.page`
+  /`.size` and resolves them to `{ page, size }`, and every `@adonis-agora/*` library is being moved
+  onto that one shape so an app (or a console) never has to remember which library counts from zero.
+  The match is **structural** — this package still depends on no filter package.
+  
+  ```ts
+  // before
+  await store.listPayments({ status: 'failed', limit: 20, offset: 40 })
+  // after — page 3 of 20, 1-based
+  await store.listPayments({ status: 'failed', size: 20, page: 3 })
+  ```
+  
+  What changed, concretely:
+  
+  - `BillingListQuery`, `PaymentListQuery`, `WebhookEventListQuery`, `CustomerListQuery`,
+    `AuditEventQuery`, `DisputeDeadlineQuery`, `OpenDisputeQuery` and
+    `listWebhookEventsForPayment`'s options: `limit`/`offset` → `size`/`page`.
+  - `AuditEventCountQuery` is now `Omit<AuditEventQuery, 'page' | 'size'>`, and
+    `countDisputesDueWithin` takes `Omit<DisputeDeadlineQuery, 'page' | 'size'>`.
+  - `BILLING_LIST_DEFAULT_LIMIT` → `BILLING_LIST_DEFAULT_SIZE` (still 50);
+    `BILLING_LIST_MAX_LIMIT` → `BILLING_LIST_MAX_SIZE` (still 200).
+  - `clampLimit`/`clampOffset` → `clampSize`/`clampPage`, plus `listOffset(page, size)` for stores
+    that need the SQL offset.
+  - Dashboard JSON API: lists read `?page=1&size=25` instead of `?limit=25&offset=0`, and echo the
+    paging back under `meta: { page, size, count, … }` instead of `page: { limit, offset, … }`.
+    `count === size` is still the only "there might be more" signal. `meta` is Lucid's own spelling —
+    `.paginate()` answers `{ meta, data }` — and it is the envelope key every `@adonis-agora` console
+    now uses.
+  - Dashboard SPA: `paymentsClient` list options take `{ page, size }`, the `Page` wire type is now
+    `ListMeta` and every list response carries it as `meta`, and the `Pager` control is page-based
+    (`page`/`size`/`onPage`). `ScanNotice` takes a `meta` prop.
+
 ## 0.11.0
 
 ### Minor Changes