BillingFlowBase — @gj-kit/toss-payments

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

검증된 import 예제

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

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

interface BillingFlowBase<E extends Env> {
    /**
     * POST /v1/billing/authorizations/issue → store.save 성공 후에만 Ok.
     * 저장 실패면 Err에 발급된 record 동봉 — 조회 API가 없으므로 저장 실패 = 키 유실이다.
     */
    issue(auth: AuthKeyReceived, options?: CallOptions<E>): Promise<Result<BillingProfile, IssueBillingKeyError>>;
    /** 스토어에서 재수화 — BillingProfile을 얻는 유일한 다른 경로(봉인 소실 복구 API). */
    load(customerKey: CustomerKey): Promise<Result<BillingProfile | null, StoreFailure>>;
    /**
     * ⚠ 마이그레이션 전용 이관 경로(§7 확정 6) — 기존 시스템이 보유한 billingKey를
     * 형식 검증 후 store.save 하고 BillingProfile로 승격한다.
     *
     * 토스에는 빌링키 조회 API가 없어 **record 값의 진위를 서버에서 재검증할 수 없다** —
     * 오염된 record면 '타입은 맞고 값은 틀린' 프로필이 만들어져 approve에서
     * INVALID_BILL_KEY_REQUEST 류로 실패한다. 신뢰할 수 있는 원본에서만 이관할 것.
     */
    import(record: BillingKeyRecord): Promise<Result<BillingProfile, ImportBillingKeyError>>;
    /**
     * BillingOrder에는 customerKey 필드가 없다 — 봉인 쌍으로만 승인 →
     * NOT_MATCHES_CUSTOMER_KEY 구조적 방지. 봉인이 소실된 profile(스프레드 복제본 등)은
     * 런타임 Err('profile-detached') — billing.load로 재수화 안내.
     *
     * options와 idempotencyKey는 모든 구성에서 필수다. TypeScript 우회를 거친 런타임 호출도
     * missing-idempotency-key로 API 전송 전에 거부한다.
     */
    readonly approve: (profile: BillingProfile, order: BillingOrder, options: CallOptions<E> & {
        readonly idempotencyKey: IdempotencyKey;
    }) => Promise<Result<BillingPayment, BillingApproveError>>;
    /**
     * DELETE /v1/billing/{billingKey} 뒤
     * `store.delete({ customerKey, expectedBillingKey: billingKey })`.
     *
     * 반환의 `currentStoredKeyDeleted`가 false면 profile은 이미 오래됐거나 행이 없어
     * 현재 저장 credential을 지우지 않았다. 갱신 API는 존재하지 않는다 — refresh류
     * 메서드 없음. 재발급 = 새 인증부터.
     */
    revoke(profile: BillingProfile, options?: CallOptions<E>): Promise<Result<RevokeBillingKeyOutcome, RevokeBillingKeyError>>;
}

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

Release context

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