parsePaymentStateSnapshot — @gj-kit/toss-payments

A public function from @gj-kit/toss-payments/server. The signature below is taken directly from the 0.6.1 release declaration.

Verified import example

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

Signature, parameters, and return type

/**
 * Validates an untrusted value (a stored/transported
 * {@link SerializedPaymentStateSnapshot}) back into a branded {@link PaymentStateSnapshot}.
 *
 * Structure is checked exhaustively — `schemaVersion: 1`, every field's type, every literal
 * against its closed union (status, lifecycle, amountState, cancelStatus, issue kinds and
 * their per-kind fields) — and `paymentKey`/`orderId` are re-branded through the existing
 * {@link paymentKey}/{@link orderId} smart constructors, keeping validation-as-the-only-path
 * to a brand intact. The first failing location is reported in `error.path`.
 *
 * Two hardening rules beyond the per-field checks:
 *
 * - **Single read.** Every own enumerable property of the untrusted value is read exactly
 *   once (a one-shot shallow copy per level) before validation, so the value that was
 *   type-checked is the value placed in the branded result — an accessor property cannot
 *   return a valid value to the check and a different one to the constructor. Inherited
 *   (prototype-supplied) properties are ignored.
 * - **Pinned arithmetic.** `canceledAmount` must equal `totalAmount - balanceAmount`
 *   whenever both amounts are safe integers — the one derivation `schemaVersion: 1` pins
 *   that {@link compareLedgerRefund}'s verdict hangs on. Snapshots whose amounts already
 *   carry `invalid-amount` issues are left to the comparison's indeterminate gate instead.
 *
 * Otherwise this is a *shape* gate, not a re-summarization: the remaining derived fields
 * (`lifecycle`, `amountState`, `isCancelable`, `consistencyIssues`, …) are trusted as data
 * produced by an earlier {@link summarizePaymentState} and are not re-derived here.
 */
declare function parsePaymentStateSnapshot(value: unknown): Result<PaymentStateSnapshot, InvalidPaymentStateSnapshot>;

This declaration is the source of truth for parameters, optionality, generics, return values, and public union/type contracts. Check the package golden path and this subpath’s import conditions for required environment, permission, and error boundaries before calling it.

Release context

• Package: @gj-kit/toss-payments
• Version: 0.6.1
• Public entry: ./server
• Source: GitHub