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

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

검증된 import 예제

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

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

/**
 * 웹훅 inbox — 이벤트 원문 보존 (설계 §3.7).
 *
 * 코어 `WebhookDedupeStore.claim`에는 이벤트 메타가 전달되지 않으므로, inbox는 스토어
 * seam이 아니라 **`WebhookHandlers`를 감싸는 헬퍼**다(코어 계약 무변경). 불변식:
 * - 사업 이벤트 1건 = 1행(dedupe_key PK). 재전송은 deliveries 증가로 관측된다.
 * - record는 핸들러 **앞**에서 실행한다 — 핸들러가 실패해도 수신 사실은 남는다
 *   (감사·재처리 목적).
 * - record 실패 기본 동작은 **삼키고 onRecordError 통지**다(AuditSink 선례 — 관측
 *   계층이 웹훅 가용성을 볼모로 잡지 않는다). `failOnRecordError: true`면 throw →
 *   어댑터 500 → 토스 재전송(inbox를 내구 계약으로 쓰는 소비자용).
 * - 저장 전 이벤트의 모든 깊이 credential/secret/billingKey/authKey/token/password/card/
 *   account 계열 키를 마스킹한다 — provider payload는 새 필드와 중첩 raw를 포함할 수
 *   있고 이 테이블은 cleanup() 대상이 아니라 무기한 보존된다. 핸들러에는 원본을
 *   그대로 주되 저장본만 별도 객체로 마스킹한다.
 */
/** 수동 기록 표면 — `withWebhookInbox`가 내부에서 쓰는 것과 동일한 단일 메서드. */
interface WebhookInboxStore {
    record(webhook: AcceptedWebhook): Promise<void>;
}

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

Release context

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

구현 주석

수동 기록 표면 — withWebhookInbox가 내부에서 쓰는 것과 동일한 단일 메서드.