IdempotencyKey — @gj-kit/toss-payments

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

검증된 import 예제

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

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

/**
 * 멱등키 — 1–300자(초과 시 400 INVALID_IDEMPOTENCY_KEY), 문자셋 `^[\x21-\x7E]+$`
 * (공백 없는 출력 가능 ASCII — 헤더 안전 집합).
 *
 * 문자셋 근거: 토스 문서는 길이만 규정하지만 값은 `Idempotency-Key` **요청 헤더**로 전송된다.
 * 비 Latin-1 문자·CR/LF는 fetch `Headers`가 TypeError로 거부해 소켓에 닿기도 전에
 * 실패하고(그 TypeError는 transport 계층에서 NETWORK_ERROR로 오분류됨), 공백·탭·Latin-1
 * 확장 문자는 중간 프록시가 trim/재인코딩할 수 있어 같은 키의 재전송이 다른 바이트로 도착할
 * 위험이 있다. 생성 시점에 거부하는 쪽이 "Ok면 전송 가능"을 보장하는 유일한 길이다.
 *
 * 처음 사용일부터 15일 유효 — TTL 초과 뒤 같은 키는 새 요청으로 실행될 수 있다(문서는 기간만
 * 명시하며 만료 뒤 동작은 서술하지 않음 — 안전하지 않은 것으로 취급).
 * 멱등 판정 조합은 "키 + API 키 + 주소 + 메서드"이며 **body는 포함되지 않는다**(문서 명시).
 */
type IdempotencyKey = string & Brand<'IdempotencyKey'>;

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

Release context

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

구현 주석

멱등키 — 1–300자(초과 시 400 INVALID_IDEMPOTENCY_KEY), 문자셋 ^[\x21-\x7E]+$ (공백 없는 출력 가능 ASCII — 헤더 안전 집합).

문자셋 근거: 토스 문서는 길이만 규정하지만 값은 Idempotency-Key 요청 헤더로 전송된다. 비 Latin-1 문자·CR/LF는 fetch Headers가 TypeError로 거부해 소켓에 닿기도 전에 실패하고(그 TypeError는 transport 계층에서 NETWORK_ERROR로 오분류됨), 공백·탭·Latin-1 확장 문자는 중간 프록시가 trim/재인코딩할 수 있어 같은 키의 재전송이 다른 바이트로 도착할 위험이 있다. 생성 시점에 거부하는 쪽이 “Ok면 전송 가능”을 보장하는 유일한 길이다.

처음 사용일부터 15일 유효 — TTL 초과 뒤 같은 키는 새 요청으로 실행될 수 있다(문서는 기간만 명시하며 만료 뒤 동작은 서술하지 않음 — 안전하지 않은 것으로 취급). 멱등 판정 조합은 “키 + API 키 + 주소 + 메서드”이며 body는 포함되지 않는다(문서 명시).