feat: sync with the API spec (v2 transactions, v2 items, SCR, balance, model fields)

[Gabrielpanga]

What

Closes #59, closes #55.

Important

getItems (GET /v2/items) is opt-in, paid plans only: disabled by default and only available to paid-plan teams that have requested it from Pluggy support. Teams without it get 403 LIST_ITEMS_FEATURE_NOT_ENABLED. Stated in the javadoc of every new class/method and in the README.

1. GET /v2/transactions (cursor pagination). GET /transactions now returns 410 This endpoint is deprecated for applications created after 2026-06-02, and the SDK had no way to call v2.

• getTransactionsV2(accountId) and getTransactionsV2(accountId, TransactionsCursorSearchRequest).
• TransactionsCursorSearchRequest only exposes the params v2 accepts (ids, dateFrom, dateTo, createdAtFrom, after): the API rejects unknown query params, so page/pageSize/from/to can't be sent by mistake. dateFrom + createdAtFrom together throws IllegalArgumentException (the API rejects that combination too).
• TransactionsCursorResponse (results, next) with getNextCursor() / hasNext(): next is a query string, not a cursor, so the helper extracts and URL-decodes after.
• Both getTransactions overloads are @Deprecated with a pointer to v2. Not removed.

2. GET /accounts/{id}/balance → getAccountBalance(accountId) returning AccountBalance (balance, currencyCode, updateDateTime). Open Finance connectors only.

3. Credit card metadata (#59): paymentType (CreditCardAccountPaymentType: SINGLE/INSTALLMENT), billPostDate (String, YYYY-MM-DD, nullable) and transactionDateTime (String, ISO-8601). Strings like billForecastDate, so a date-only value can't shift by timezone. Open Finance only, not retroactive.

4. Jackson deserialization (#55): @NoArgsConstructor + @AllArgsConstructor on every @Builder response class (49) and request/Options. Left alone: CreateItemRequest / CreateConnectTokenRequest (@Value, final fields, only ever serialized) and CredentialLabel (already has a hand-written no-args constructor).

5. GET /v2/items → getItems() / getItems(ItemsCursorSearchRequest) returning ItemsCursorResponse (results, next, getNextCursor(), hasNext()). The request only sends clientUserId, connectorId and after, and rejects a clientUserId over 255 characters or a negative connectorId up front. ErrorResponse gains codeDescription, so callers can tell LIST_ITEMS_FEATURE_NOT_ENABLED apart (the API sends code: 403 and the identifier in codeDescription). The cursor parser moves to ai.pluggy.utils.Cursors; TransactionsCursorResponse.parseAfterCursor still works.

6. Sync with the API spec. Fields the API returns that the models were missing:

• ItemResponse: consentExpiresAt, nextAutoSyncAt, userAction
• CreditData: additionalCards, isLimitFlexible
• Transaction: order
• Connector: productCoverage, supportsAutomaticPix
• Investment: couponPayment, debtor, gracePeriodDate, priceFactor, taxExempt
• IdentityResponse: establishmentCode, establishmentName, relations, financialRelationships, qualifications
• Bill: payments
• PaymentData: authenticationCode, receiverReferenceId

IdentityResponse.identityRelations is now @Deprecated: the API sends that list as relations, so it was never filled. Investment.amountProfit stays a String (the API sends a number, Gson reads it into the String) so this release doesn't break callers. Enum-like values the spec lists (e.g. userAction.type) are typed as String, so an unknown value doesn't silently become null.

7. GET /items/{id}/scr → getItemScr(itemId) / getItemScr(itemId, from, to) returning ScrResponse. Opt-in: requires the SCR feature (403 SCR_FEATURE_NOT_ENABLED otherwise) and only works for Open Finance items with a known CPF/CNPJ (422 SCR_ITEM_NOT_SUPPORTED).

8. README: v2 transactions and opt-in items pagination loops. Version bumped to 1.15.0 so the merge cuts a release.

Tests

New unit tests (no network): TransactionsV2Test (v2 page parsing with the new card fields, last page, unknown paymentType → null, exact query params on the wire with a cursor containing +/=, the dateFrom/createdAtFrom conflict, cursor parsing edge cases, getAccountBalance path) BuilderNoArgsConstructorTest and ItemsV2Test (page parsing, only the three params on the wire with the cursor intact, last page, the 403 parsed to codeDescription, request validation). plus ResponseFieldsTest (one sample per class with nested objects, null cases) and ItemScrTest (path, query, payload, 403/422 codeDescription). mvn -B test: 39/39.

The existing integration tests (GetTransactionsTest, TransactionHelper) still call /transactions; they will get the 410 if the CI application was created after the cutoff.

After merge

Per the release flow, release.yml tags v1.15.0, then publishing needs gh workflow run maven-publish.yml -f tag_version=v1.15.0.

[Gabrielpanga]

@cursor review this