10 Commits

Author SHA1 Message Date
qbirr agent 5008b3de5a Document tolerance, max_age_hours and payer_error
The API accepts per-call overrides for the underpayment limit ("25" = 25 ETB,
"1%" = one percent) and the receipt age limit (hours, 0 disables), and returns
payer_error alongside error. None of it was in this SDK.

payer_error is the payer-facing wording: show it to the customer, because error
is written for the merchant and can name their own saved accounts.
2026-10-06 19:34:08 +03:00
admin eb856ee944 docs: fix the install command — it did not work
Every SDK shipped an install command that fails. A developer following the
README hits an error on the first step.

- go: `go get github.com/qbirr/sdk-go` pointed at GitHub. The module lives at
  git.qbirr.com/admin/sdk-go (see go.mod), so that command could never work.
- node / python / php: the commands assumed a published package, but nothing is
  on npm, PyPI or Packagist yet (all four return 404).

The commands are now the ones that were actually run and verified:
  go      go get git.qbirr.com/admin/sdk-go
  node    npm install git+https://git.qbirr.com/admin/sdk-node.git
  python  pip install "git+https://git.qbirr.com/admin/sdk-python.git"
  php     composer config repositories.qbirr vcs <repo>
          composer require qbirr/sdk:dev-main

A note under each explains that the package is not on the public registry yet,
so the install comes straight from the repository.

The repositories stay public, so no credentials are needed for any of the above.
If they were made private, the Go install would break first: Go fetches modules
directly from the git host.
2026-10-06 01:17:50 +03:00
admin 322a1154b9 Docs + scrub: neutral example account number, CBE reference formats, webhooks, quota
- The example account number in the README and in the source docblock was a
  REAL account number. Replaced with an obviously fake one (1000123456789).
  The same scrub had already been applied to sdks/ in qbirr-saas; this repo
  had drifted from it.
- Document that CBE accepts the full receipt link, the "v2-" token and the bare
  token as the SAME payment. qbirr reduces them to one identity, so a receipt
  cannot be verified twice by presenting it differently. Case is ignored for
  that check.
- Document the webhook contract: `verification.created` fires for BOTH outcomes
  so always read data.verified; data.client_ref echoes the tag your own upload
  sent (null if you did not send one); a 4xx response is final and is NOT
  retried, while 5xx / timeouts are retried with exponential backoff.
- Document that only verified lookups count against the monthly quota.
- sdk-node: the committed dist/ comment blocks were updated to match src. The
  change is inside comments only — no executable code differs.
2026-10-06 01:05:06 +03:00
admin a0dcd4fd23 feat: expose paid_amount, retryable, code, receiver_source, sandbox
The API returns five fields the SDKs were dropping, so a caller could not
act on any of them:

  retryable        TRUE means we could not reach the bank. In that case
                   verified=false is NOT a verdict on the payment -- it is
                   "not checked yet". Retry, or fall back to manual review.
                   Never reject an order on it. Check it BEFORE acting on
                   verified=false.
  code             Stable machine-readable reason; branch on this instead of
                   parsing the human-readable error string. Empty/null on
                   success. RECEIPT_NOT_FOUND, AMOUNT_MISMATCH,
                   RECEIVER_MISMATCH, RECEIPT_EXPIRED, RECEIPT_UNREADABLE,
                   REFERENCE_INVALID, RECEIVER_ACCOUNT_REQUIRED,
                   UNSUPPORTED_INPUT, VERIFICATION_FAILED,
                   DUPLICATE_REFERENCE, UPSTREAM_UNAVAILABLE (retryable).
  paid_amount      What the receipt ACTUALLY shows, so a short payment can be
                   compared to the expected figure rather than only described
                   in prose.
  receiver_source  Which receiver identity was actually checked: 'settings'
                   (your saved dashboard account -- strongest), 'request' (the
                   receiver_name/account you sent), or 'none' (NOTHING was
                   checked: verified=true with 'none' means the reference
                   exists and the amount matches, but says nothing about who
                   received the money).
  sandbox          True only on TEST-... responses.

Additive only. Defaults are filled in on the way out so a caller never sees a
missing value, including against an API build that predates these fields.
2026-10-01 00:44:02 +03:00
admin f7e858ca20 feat: prebuild dist for ESM + CJS 2026-07-17 16:52:53 +02:00
admin c233cb0000 fix: generate CJS build for require() support 2026-07-17 16:51:47 +02:00
admin 1ad14f70a1 fix: type cast BlobPart for TS 5.9 compat 2026-07-17 16:51:01 +02:00
admin 7483bcd497 fix: bump typescript to ^5.7 for node 22 compat 2026-07-17 16:49:17 +02:00
admin d6983afe9c fix: add prepare script so npm install builds TypeScript 2026-07-17 16:48:39 +02:00
admin 137045b1a6 Initial release: @qbirr/sdk v1.0.0 2026-07-17 16:42:18 +02:00