createPgCancelRetryStore — @gj-kit/toss-payments-postgresql

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

검증된 import 예제

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

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

/**
 * CancelRetryStore PostgreSQL 구현 (설계 §3.4).
 *
 * 코어 계약의 핵심 불변식:
 * - `CancelRetryRecord.bodyJson`은 **멱등 재생의 바이트 계약**이다 — 재시도 시 동일
 *   멱등키 + 동일 바이트를 다시 보내야 한다. 그래서 record_json 컬럼은 jsonb가 아니라
 *   **text**다: JSON.stringify한 record 전체를 보호한 뒤 text로 저장하고 JSON.parse
 *   왕복해 문자열 필드를 무손실 복원한다. jsonb 정규화(NUL 거부, 이스케이프/키 정렬
 *   변형)는 원문을 바꿀 위험이 있어 사용하지 않는다.
 * - 멱등키 15일 TTL — 삭제는 cleanup()(팩토리) 소관이며 이 스토어는 지우지 않는다.
 * - ⚠ record에는 환불 계좌 정보가 평문으로 들어올 수 있다. 레코드 전체를 보호기에
 *   넘긴 뒤 저장하며, 어떤 에러 메시지에도 record 내용을 싣지 않는다.
 */
declare function createPgCancelRetryStore(sql: SqlExecutor, options: PgSensitiveStoreOptions): CancelRetryStore;

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

Release context

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

구현 주석

CancelRetryStore PostgreSQL 구현 (설계 §3.4).

코어 계약의 핵심 불변식:

• CancelRetryRecord.bodyJson은 멱등 재생의 바이트 계약이다 — 재시도 시 동일 멱등키 + 동일 바이트를 다시 보내야 한다. 그래서 record_json 컬럼은 jsonb가 아니라 text다: JSON.stringify한 record 전체를 보호한 뒤 text로 저장하고 JSON.parse 왕복해 문자열 필드를 무손실 복원한다. jsonb 정규화(NUL 거부, 이스케이프/키 정렬 변형)는 원문을 바꿀 위험이 있어 사용하지 않는다.
• 멱등키 15일 TTL — 삭제는 cleanup()(팩토리) 소관이며 이 스토어는 지우지 않는다.
• ⚠ record에는 환불 계좌 정보가 평문으로 들어올 수 있다. 레코드 전체를 보호기에 넘긴 뒤 저장하며, 어떤 에러 메시지에도 record 내용을 싣지 않는다.