Improve Python SDK to support Core 0.15.3

[stkegoul]

Blnk Core 0.15.3 is out. This SDK still targets 0.15.0 (1.3.0) and is missing the new request fields, response types, and coverage below.

Core changelog: https://docs.blnkfinance.com/changelog/blnk-core

Missing support

1. Dry-run transactions (dry_run)

Core can preview a post without writing a transaction, queue entry, webhook, hook, or @ balance. The reference is not consumed. The preview always returns HTTP 200; a projected rejection is would_apply: false, not an HTTP error. dry_run takes precedence over skip_queue.

Add optional dry_run (default False) to:

• blnk.transactions.create (POST /transactions)
• blnk.transactions.create_bulk (POST /transactions/bulk)
• blnk.transactions.refund (POST /refund-transaction/{id})
• blnk.transactions.update_status (PUT /transactions/inflight/{id})
• blnk.transactions.bulk_commit_inflight
• blnk.transactions.bulk_void_inflight

Add a typed dry-run response (do not treat it as a recorded transaction). Shape:

• dry_run: true
• would_apply: boolean
• rejection?: { code, reason, message } when would_apply is false (code is the same catalog code a real post would return)
• status, reference, currency, amount, precise_amount (string), precision
• operation on inflight previews (commit | void)
• balances[] with balance_id, role, currency, virtual, and current_* / resulting_* minor-unit strings

For bulk and splits, skip_queue still selects cumulative vs independent projection. run_async is ignored on a bulk dry run.

Docs: Dry-run transactions · Dry-run a transaction

2. Create internal balances (indicator)

You can now create a General Ledger balance yourself. ledger_balances.create has no indicator field.

• Accept optional indicator on create
• Callers send ledger_id: "general_ledger_id" and an @ indicator (no whitespace), e.g. @Revenue
• Duplicate indicator + currency returns 409 with GEN_CONFLICT
• indicator is only valid when ledger_id is general_ledger_id

Docs: Internal balances · Create balance

3. Refund description and meta_data

Refund currently only documents skip_queue. Core 0.15.3 also accepts:

• description — narration for the refund. When omitted or empty, Core copies the original transaction's description
• meta_data — merged onto metadata inherited from the original. Sent keys replace matching keys; other keys stay. An empty object is ignored. The original transaction is not modified

Docs: Refund transaction

4. List hooks without a type

GET /hooks without type now returns all hooks (PRE and POST). Confirm blnk.hooks.list() works with no type filter. If the SDK currently requires type, make it optional.

Docs: List hooks

5. Validation errors to recognize

No new endpoints. Surface these structured codes when Core rejects a request:

• TXN_INVALID_AMOUNT — negative amount, precise_amount, or precision
• Source equal to destination is rejected before processing
• GEN_CONFLICT — duplicate internal-balance indicator + currency

Docs: API error codes

Out of scope (Core-only, no SDK API change)

• Official image is now ghcr.io/blnkfinance/blnk
• Committed/voided transactions no longer keep meta_data.inflight: true
• Typesense keeps balance meta_data after a transaction
• Scoped keys can update metadata with metadata:write

Acceptance criteria

• dry_run on create, bulk create, refund, update inflight, bulk commit, and bulk void
• Typed dry-run response (would_apply, rejection, balances)
• indicator on ledger_balances.create with ledger_id: "general_ledger_id"
• description and meta_data on transactions.refund
• hooks.list() without type returns all hooks
• Tests against Core 0.15.3
• Changelog + version bump covering Core 0.15.3