DEFAULT_IDEMPOTENCY_REPLAY_WINDOW_MS — @gj-kit/toss-payments

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

검증된 import 예제

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

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

DEFAULT_IDEMPOTENCY_REPLAY_WINDOW_MS: number

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

Release context

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

구현 주석

Conservative replay window used by {@link isWithinIdempotencyReplayWindow} when no explicit window is given: 14 days — one full day of margin below {@link TOSS_IDEMPOTENCY_KEY_TTL_MS}.

Two regimes split at this boundary:

• Replay within the window — resending the same key with the same body is safe: if the first request reached Toss, the original response is replayed byte-for-byte and nothing is executed twice; if it never arrived, it runs once now.
• New attempt after the window — the same key may be executed as a brand-new request. Do not resubmit. The only safe automatic action is to look the outcome up (getPaymentByOrderId / getPayment) and decide from the durable state; a genuinely new charge needs a new key (a new attempt) and an explicit decision.

Why a day of margin: the provider states the window at day granularity (“15 days from first use”) without specifying the boundary or time zone, so the real cutoff may land earlier than 15 × 24 h after the first request; and the caller’s clock and the provider’s clock drift. A whole day absorbs both without guessing. The precondition this relies on is that issuedAt was recorded no later than the first network attempt — then it is a lower bound on the provider’s first-use time and a window measured from it can only be conservative. The library’s own CancelRetryTicket expires on this same 14-day window.