TossEventMap — @gj-kit/toss-payments

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

검증된 import 예제

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

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

interface TossEventMap {
    /**
     * 요청 라이프사이클 — started/succeeded/failed 3분할 대신 완료 1종(과설계 금지).
     * 논리 요청당 1회(최종 outcome). durationMs는 첫 시도 시작부터 최종 outcome 확정까지의
     * 총 경과(재시도 대기 포함) — 시도별 소요는 audit(§3.2)의 AuditEntry.durationMs로.
     */
    'api.call': {
        readonly method: string;
        readonly path: string;
        readonly outcome: 'ok' | 'toss-error' | 'transport';
        readonly httpStatus: number | null;
        readonly durationMs: number;
        readonly traceId: string | null;
        /** retry(§3.4) 결합 시 총 시도 수 — 미결합이면 1. */
        readonly attempts: number;
    };
    /**
     * store 검증 통과 후 Ok 확정 시점.
     * ⚠ payment에 secret 포함 가능(실측: BILLING 카드 결제도 non-null) — payload 통짜 로깅
     * 금지. 기록 용도는 audit(§3.2)으로(redaction 통과본만 기록된다).
     */
    'payment.confirmed': {
        readonly payment: ConfirmedPayment;
    };
    'payment.confirm-failed': {
        /** parse 단계 실패면 null. */
        readonly orderId: OrderId | null;
        readonly error: CallbackParseError | VerifyCheckoutError | ConfirmError;
    };
    'cancel.executed': {
        readonly outcome: CancelOutcome;
    };
    'cancel.failed': {
        readonly paymentKey: PaymentKey;
        readonly error: CancelError;
    };
    /** billingKey는 payload 원천 부재 — 봉인 원칙 유지(유출 원천 차단). */
    'billing.issued': {
        readonly customerKey: CustomerKey;
    };
    'billing.approved': {
        readonly payment: BillingPayment;
        readonly customerKey: CustomerKey;
    };
    'billing.approve-failed': {
        readonly customerKey: CustomerKey;
        readonly error: BillingApproveError;
    };
    'billing.revoked': {
        readonly customerKey: CustomerKey;
    };
    /** §3.1 depositSecrets 연동. */
    'deposit.secret-saved': {
        readonly orderId: OrderId;
    };
    'deposit.secret-save-failed': {
        readonly orderId: OrderId;
        readonly paymentKey: PaymentKey;
        readonly cause: unknown;
    };
    /** 요약만 — AcceptedWebhook 통짜 전달 대신 secret 제거·타입 순환 회피가 보장되는 최소 필드. */
    'webhook.accepted': {
        readonly trust: 'signature' | 'secret' | 'unverified';
        readonly eventType: string;
        readonly transmissionId: string;
    };
    'webhook.duplicate': {
        readonly transmissionId: string;
    };
    'webhook.rejected': {
        readonly rejection: WebhookRejection;
    };
}

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

Release context

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