LedgerRefundComparison — @gj-kit/toss-payments

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

검증된 import 예제

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

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

/**
 * Verdict of {@link compareLedgerRefund} — a three-way discriminated union.
 *
 * Balance model (Phase-0 field measurements, enforced by the cancel path's response
 * validation): an accepted async cancel *already* reduces `balanceAmount` while its
 * `cancelStatus` is `IN_PROGRESS`; completion (`DONE`) keeps the reduction, abortion
 * (`ABORTED`) restores the balance. `snapshot.canceledAmount` therefore *includes*
 * in-flight amounts, and the final confirmed amount lies in
 * `[canceledAmount - pendingCancelAmount, canceledAmount]`.
 *
 * - `'settled'` — `snapshot.canceledAmount` equals the ledger target **and no cancel is in
 *   flight** (`pendingCancelAmount` is always `0` here). Only then is recording the refund
 *   as final safe: an `IN_PROGRESS` cancel could still resolve `ABORTED` and take the
 *   balance back up (money that never moved).
 * - `'unconfirmed'` — at least one `IN_PROGRESS` cancel keeps the verdict provisional, and
 *   the target lies within the possible final range above, so it may still settle without
 *   any new provider action. Do not settle the ledger yet; re-fetch the payment (a
 *   `CANCEL_STATUS_CHANGED` webhook is `unverified`) and compare again. This mirrors
 *   `lifecycle: 'cancellation-pending'` taking priority over amount-based `'full'`.
 * - `'mismatch'` — the target is outside every possible outcome (`direction` says which
 *   way; with `requestedAmount` supplied, `shortfall` splits `'provider-below-ledger'` into
 *   `'at-prior-state'` / `'unexplained'`), or the comparison is impossible
 *   (`direction: 'indeterminate'`): the snapshot's amounts carry consistency issues
 *   (attached in `consistencyIssues`), or the ledger target itself was invalid
 *   (`invalidLedgerTarget: true`).
 */
type LedgerRefundComparison = {
    readonly kind: "settled";
    /** Provider-confirmed cumulative canceled amount (`snapshot.canceledAmount`). */
    readonly canceledAmount: number;
    /** Always `0` in this verdict — any in-flight cancel forces `'unconfirmed'`. */
    readonly pendingCancelAmount: number;
    readonly expectedRefundedAmount: number;
} | {
    readonly kind: "unconfirmed";
    readonly canceledAmount: number;
    readonly pendingCancelAmount: number;
    readonly expectedRefundedAmount: number;
} | {
    readonly kind: "mismatch";
    readonly direction: LedgerRefundMismatchDirection;
    readonly canceledAmount: number;
    readonly pendingCancelAmount: number;
    readonly expectedRefundedAmount: number;
    /**
     * `true` when `expectedRefundedAmount` (or a supplied `requestedAmount`) was not a
     * valid ledger amount.
     */
    readonly invalidLedgerTarget: boolean;
    /**
     * Present only when `direction: 'provider-below-ledger'` and the ledger supplied
     * `requestedAmount` — see {@link LedgerRefundShortfall}.
     */
    readonly shortfall?: LedgerRefundShortfall;
    /**
     * The amount-integrity issues that blocked the comparison (`invalid-amount`,
     * `balance-exceeds-total`) — empty for a plain amount mismatch. The snapshot keeps
     * the full issue list.
     */
    readonly consistencyIssues: readonly PaymentStateConsistencyIssue[];
};

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

Release context

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

구현 주석

Verdict of {@link compareLedgerRefund} — a three-way discriminated union.

Balance model (Phase-0 field measurements, enforced by the cancel path’s response validation): an accepted async cancel already reduces balanceAmount while its cancelStatus is IN_PROGRESS; completion (DONE) keeps the reduction, abortion (ABORTED) restores the balance. snapshot.canceledAmount therefore includes in-flight amounts, and the final confirmed amount lies in [canceledAmount - pendingCancelAmount, canceledAmount].

• 'settled' — snapshot.canceledAmount equals the ledger target and no cancel is in flight (pendingCancelAmount is always 0 here). Only then is recording the refund as final safe: an IN_PROGRESS cancel could still resolve ABORTED and take the balance back up (money that never moved).
• 'unconfirmed' — at least one IN_PROGRESS cancel keeps the verdict provisional, and the target lies within the possible final range above, so it may still settle without any new provider action. Do not settle the ledger yet; re-fetch the payment (a CANCEL_STATUS_CHANGED webhook is unverified) and compare again. This mirrors lifecycle: 'cancellation-pending' taking priority over amount-based 'full'.
• 'mismatch' — the target is outside every possible outcome (direction says which way; with requestedAmount supplied, shortfall splits 'provider-below-ledger' into 'at-prior-state' / 'unexplained'), or the comparison is impossible (direction: 'indeterminate'): the snapshot’s amounts carry consistency issues (attached in consistencyIssues), or the ledger target itself was invalid (invalidLedgerTarget: true).