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

A public interface from @gj-kit/toss-payments-postgresql. The signature below is taken directly from the 0.5.1 release declaration.

Verified import example

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

Signature, parameters, and return type

/**
 * 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>;
}

This declaration is the source of truth for parameters, optionality, generics, return values, and public union/type contracts. Check the package golden path and this subpath’s import conditions for required environment, permission, and error boundaries before calling it.

Release context

• Package: @gj-kit/toss-payments-postgresql
• Version: 0.5.1
• Public entry: .
• Source: GitHub