compareLedgerRefund — @gj-kit/toss-payments

@gj-kit/toss-payments에서 공개하는 function입니다. package version 0.6.1의 release declaration을 그대로 표시합니다.

검증된 import 예제

import { compareLedgerRefund } from '@gj-kit/toss-payments';

시그니처, 매개변수, 반환 타입

/**
 * Compares a provider payment-state snapshot against the app ledger's cumulative refund
 * target — "has the provider confirmed the refunds my ledger claims?".
 *
 * Expressed purely in provider-snapshot terms: `snapshot.canceledAmount`
 * (`totalAmount - balanceAmount` at summarize time) is the provider's current cumulative
 * canceled amount, and `pendingCancelAmount` is the sum of `cancelAmount` over
 * `cancelStatus: 'IN_PROGRESS'` transactions. Per the kit's Phase-0 field measurements
 * (and the cancel path's own 2xx validation), an accepted async cancel already shows the
 * reduced balance while `IN_PROGRESS` — so pending amounts are *inside* `canceledAmount`,
 * and an aborted cancel takes the balance back up. `'settled'` therefore additionally
 * requires that nothing is in flight; see {@link LedgerRefundComparison} for the exact
 * three-way semantics. The ledger target stays app-owned — see {@link LedgerRefundTarget}.
 * Both the branded and the serialized snapshot forms are accepted; the ids play no part in
 * the verdict, so no re-branding is required. Comparing a snapshot of the *wrong payment*
 * against a ledger target is a caller-side identity error this helper cannot detect.
 *
 * Mapping to an app-side `SUCCEEDED / UNCONFIRMED / MISMATCH` three-way: `'settled'` maps
 * to succeeded, but the kit's `'unconfirmed'` is strictly the in-flight-cancel case — an
 * app-style "the cancel request likely never reached the provider, replay the sealed
 * request" state surfaces here as `'mismatch'` / `'provider-below-ledger'`. Pass
 * {@link LedgerRefundTarget.requestedAmount} to have that case labelled
 * `shortfall: 'at-prior-state'` (vs `'unexplained'`); do not map the three kit names 1:1
 * onto an app's replay policy without it.
 *
 * Honesty rule for broken inputs: when the snapshot's amounts are untrustworthy
 * (`invalid-amount`/`balance-exceeds-total` issues, or a `canceledAmount` that is not a
 * non-negative safe integer), the verdict is `'mismatch'` with
 * `direction: 'indeterminate'` and the gating issues attached. Deliberately *not*
 * reproduced: the "status CANCELED with only totalAmount valid ⇒ assume fully refunded"
 * fallback some reconciliation paths use — that is a guess, and settling a ledger on it
 * belongs to the app's explicit policy, not a library default.
 */
declare function compareLedgerRefund(snapshot: PaymentStateSnapshot | SerializedPaymentStateSnapshot, ledger: LedgerRefundTarget): LedgerRefundComparison;

이 선언은 매개변수, optionality, 제네릭, 반환값, 공개 union/type 계약의 정본입니다. 호출 전 필요한 환경·권한·오류 경계는 패키지 Golden path와 이 subpath의 import 조건을 함께 확인하세요.

Release context

• 패키지: @gj-kit/toss-payments
• 버전: 0.6.1
• 공개 entry: .
• 소스: GitHub

구현 주석

Compares a provider payment-state snapshot against the app ledger’s cumulative refund target — “has the provider confirmed the refunds my ledger claims?”.

Expressed purely in provider-snapshot terms: snapshot.canceledAmount (totalAmount - balanceAmount at summarize time) is the provider’s current cumulative canceled amount, and pendingCancelAmount is the sum of cancelAmount over cancelStatus: 'IN_PROGRESS' transactions. Per the kit’s Phase-0 field measurements (and the cancel path’s own 2xx validation), an accepted async cancel already shows the reduced balance while IN_PROGRESS — so pending amounts are inside canceledAmount, and an aborted cancel takes the balance back up. 'settled' therefore additionally requires that nothing is in flight; see {@link LedgerRefundComparison} for the exact three-way semantics. The ledger target stays app-owned — see {@link LedgerRefundTarget}. Both the branded and the serialized snapshot forms are accepted; the ids play no part in the verdict, so no re-branding is required. Comparing a snapshot of the wrong payment against a ledger target is a caller-side identity error this helper cannot detect.

Mapping to an app-side SUCCEEDED / UNCONFIRMED / MISMATCH three-way: 'settled' maps to succeeded, but the kit’s 'unconfirmed' is strictly the in-flight-cancel case — an app-style “the cancel request likely never reached the provider, replay the sealed request” state surfaces here as 'mismatch' / 'provider-below-ledger'. Pass {@link LedgerRefundTarget.requestedAmount} to have that case labelled shortfall: 'at-prior-state' (vs 'unexplained'); do not map the three kit names 1:1 onto an app’s replay policy without it.

Honesty rule for broken inputs: when the snapshot’s amounts are untrustworthy (invalid-amount/balance-exceeds-total issues, or a canceledAmount that is not a non-negative safe integer), the verdict is 'mismatch' with direction: 'indeterminate' and the gating issues attached. Deliberately not reproduced: the “status CANCELED with only totalAmount valid ⇒ assume fully refunded” fallback some reconciliation paths use — that is a guess, and settling a ledger on it belongs to the app’s explicit policy, not a library default.