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

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

검증된 import 예제

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

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

/**
 * BillingKeyStore PostgreSQL 구현 (설계 §3.3).
 *
 * 코어 계약의 핵심 불변식:
 * - 토스에 빌링키 조회 API가 없다 — **저장 실패 = 복구 불가**. 이 테이블이 유일한
 *   보관 수단이므로 save는 드라이버 에러를 감추지 않고 그대로 던진다(코어가 감쌈).
 * - `save`는 upsert(customer_key)다 — issue/import 양쪽에서 호출되는 계약이고 코어가
 *   교체 정책을 규정하지 않으므로 최신 발급본을 유지한다.
 * - `billing_key`에는 BillingKeyRecord 전체의 보호된 JSON 문자열만 쓴다. `card`와
 *   `transfers`까지 함께 보호해 계좌번호 등 부수 메타데이터가 jsonb에 평문으로 남지
 *   않게 한다. method/issued_at은 운영 조회용 비밀이 아닌 최소 메타데이터로만 남긴다.
 * - ⚠ 보안 불변식(코어 stores.ts): 어떤 에러 메시지에도 billing_key 값을 싣지 않고,
 *   customerKey와 billingKey를 같은 문자열(로그 한 줄)에 함께 두지 않는다 — 토스의
 *   빌링 보안 모델이 이 쌍의 분리에 의존한다. 이 파일의 메시지는 둘 다 싣지 않는다.
 */
/**
 * `withMutationLock` callback에만 전달되는 customerKey-고정 mutation handle.
 *
 * 핸들은 lock을 잡은 customerKey 하나만 조작한다. callback 안에서 바깥
 * `pg.billingKeys`를 다시 호출하면 다른 커넥션이 같은 advisory lock을 기다려 deadlock이
 * 되므로, 모든 billing key 작업은 이 handle을 통해 수행해야 한다.
 */
interface PgBillingKeyMutation {
    readonly customerKey: BillingKeyRecord['customerKey'];
    find(): Promise<BillingKeyRecord | null>;
    save(record: BillingKeyRecord, options?: BillingKeySaveOptions): Promise<void>;
    /**
     * 현재 raw billing key와 일치할 때만 삭제한다. 무조건 삭제 API는 의도적으로 없다.
     */
    delete(expectedBillingKey: BillingKeyRecord['billingKey']): Promise<boolean>;
    replaceAndGetPrevious(record: BillingKeyRecord, options?: BillingKeySaveOptions): Promise<PgBillingKeySnapshot | null>;
    /**
     * 저장 당시의 nonsecret operationId fingerprint가 예상 operationId와 같은지 확인한다.
     * callback 내부에서만 쓰며 raw operationId/fingerprint 어느 것도 반환하지 않는다.
     */
    isCurrentOperationId(operationId: string): Promise<boolean>;
    deleteIfBillingKeyMatches(expectedBillingKey: BillingKeyRecord['billingKey']): Promise<boolean>;
    replaceIfBillingKeyMatches(expectedBillingKey: BillingKeyRecord['billingKey'], replacement: BillingKeyRecord | PgBillingKeySnapshot | null): Promise<boolean>;
}

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

Release context

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

구현 주석

withMutationLock callback에만 전달되는 customerKey-고정 mutation handle.

핸들은 lock을 잡은 customerKey 하나만 조작한다. callback 안에서 바깥 pg.billingKeys를 다시 호출하면 다른 커넥션이 같은 advisory lock을 기다려 deadlock이 되므로, 모든 billing key 작업은 이 handle을 통해 수행해야 한다.