TossPaymentsBaseConfig — @gj-kit/toss-payments

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

Verified import example

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

Signature, parameters, and return type

/**
 * createTossPayments 파사드 — 배선을 누락할 수 없는 조립층 (설계 §2, G2).
 *
 * **순수 조립층**이다: 기존 팩토리 4종(createTossClient/createConfirmFlow/
 * createBillingFlow/createWebhookVerifier)에 전량 위임하고 검증 로직 중복이 0이다.
 * 배선하지 않은 플로우는 반환 타입에 **프로퍼티 자체가 없어** 사용 시점에 컴파일
 * 에러가 난다 — "스토어 미제공 시 플로우 생성 불가"라는 기존 런타임 보장을 타입으로
 * 옮긴 것뿐, 새 동작이 없다.
 *
 * 확정 판정(§2):
 * - flat config + 오버로드 2종 — 중첩(keys/stores/options)은 조건부 타입 판정 경로를
 *   깊게 만들어 추론 취약성만 늘린다.
 * - 단일 키 = 파사드 1개 — 위젯 결제 + 빌링 병용 상점은 파사드 2개(gsk용/sk용)를
 *   만든다. 키 쌍 규칙이 파사드 경계와 일치해 "confirm은 위젯 client 우선" 같은
 *   새 암묵 규칙이 생기지 않는다.
 * - raw string 키 미수용(§7-1 기각) — Env phantom 소실·실패 시점 이원화.
 */
interface TossPaymentsBaseConfig<E extends Env> {
    /** confirm 플로우 배선 — 미지정 시 반환 타입에 `confirm` 부재. */
    readonly orders?: OrderStore;
    /**
     * G1 — 1회 배선으로 confirm측 자동 저장 + webhook측 getSecret 대조 양쪽 커버 (§3.1).
     * README의 수동 저장 한 줄(`db.deposits.save`)이 사라진다.
     */
    readonly depositSecrets?: DepositSecretStore;
    /**
     * §3.1 saveSecret 실패 통지 — payload에 secret 원문 미포함(로그 유출 방지).
     * 미지정 시 실패 1건당 console.warn 1회. 복구: `getPaymentByOrderId(orderId)` →
     * `Payment.secret` → `saveSecret` 재시도.
     */
    readonly onDepositSecretSaveFailed?: (info: {
        readonly orderId: OrderId;
        readonly paymentKey: PaymentKey;
        readonly cause: unknown;
    }) => void;
    /** webhook 배선 — 미지정 시 반환 타입에 `webhook` 부재. depositSecrets는 위 필드가 자동 배선. */
    readonly webhook?: {
        readonly dedupe: WebhookDedupeStore;
        readonly securityKeys?: readonly SecurityKey[];
        readonly allowedSourceIps?: readonly string[] | false;
        /** 서명 이벤트 전송 시각의 과거/미래 허용 폭. 기본 5분. */
        readonly transmissionTimeToleranceMs?: number | false;
        /** 테스트 또는 통제된 런타임의 시계 주입용. */
        readonly clock?: () => Date;
        /** true → 파사드 내부 client를 PaymentLookup으로 자동 결속 (§3.5 배선 1비트). */
        readonly autoRefetch?: true;
    };
    /**
     * 옵션 3종 — 기본 전부 꺼짐. events는 client·confirm·billing·webhook 4곳에 자동 배선된다.
     * 미주입 시 반환 kit의 `events`는 no-op 구독 표면(발행 지점 순회 0회)이다.
     */
    readonly events?: TossEvents;
    readonly audit?: AuditOptions;
    readonly retry?: RetryOptions;
    /** 취소 transport 실패 재시도 티켓의 영속 저장소. */
    readonly cancelRetries?: CancelRetryStore;
    /** fetch/baseUrl/timeoutMs — audit/retry/events는 파사드가 위 필드에서 병합 주입한다. */
    readonly client?: Pick<TossClientOptions, 'fetch' | 'baseUrl' | 'timeoutMs' | 'dangerouslyAllowCustomLiveBaseUrl'>;
    readonly confirm?: Pick<ConfirmFlowOptions, 'approvalWindowMs' | 'clock'>;
}

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
• Version: 0.6.1
• Public entry: ./server
• Source: GitHub