AuditEntry — @gj-kit/toss-payments

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

검증된 import 예제

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

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

/**
 * audit — 아웃바운드 토스 API req/res 증거 기록 (설계 §3.2, must 3/3 수렴).
 *
 * 타입뿐인 계약 + 순수 redaction 순회기 — 환경 중립(core)이며 런타임 의존성 0.
 * 부착 지점은 server/client.ts의 내부 request() 단일 관문이다(흩어짐 없음).
 *
 * 협상 불가 계약:
 * - `record()`는 await되지 않는다(fire-and-forget) — audit 오류가 결제 요청의
 *   지연·실패에 영향을 주는 경로가 없다(기록 실패 < 결제 실패).
 * - redaction은 비설정화 — 끄는 옵션·설정 파라미터를 제공하지 않는다.
 * - Authorization 헤더는 AuditEntry에 **필드 자체가 없다** — 마스킹이 아니라 구조적 부재.
 */
/**
 * 시도 1건 = 엔트리 1건 (outcome 유니언) — request/response 분리 kind안은
 * 상관(join) 비용 때문에 기각(설계 §7-7).
 *
 * ⚠ responseBody에는 redaction 후에도 고객 이름·이메일 등 PII가 잔존할 수 있다 —
 * 보관 주체·기간·접근 통제는 sink 소유자(사용자) 책임이다.
 */
interface AuditEntry {
    /** crypto.randomUUID — 시도 1건당 1엔트리. */
    readonly id: string;
    /** ISO 8601 요청(시도) 시작 시각. */
    readonly at: string;
    readonly env: Env;
    readonly method: 'GET' | 'POST' | 'DELETE';
    /** '/v1/payments/confirm' 등 pathname만 — 쿼리 미포함. */
    readonly path: string;
    /** 1부터 — retry(§3.4) 결합 시 시도마다 엔트리 1건. */
    readonly attempt: number;
    readonly idempotencyKey: string | null;
    /** redaction 통과본. ⚠ 헤더 필드가 타입에 없다 — Authorization은 구조적으로 기록 불가. body 없는 요청은 null. */
    readonly requestBody: unknown;
    readonly durationMs: number;
    /** x-tosspayments-trace-id — 고객센터 문의 키. */
    readonly traceId: string | null;
    readonly outcome: {
        readonly kind: 'ok';
        readonly httpStatus: number;
        /** redaction 통과본. */
        readonly responseBody: unknown;
    } | {
        readonly kind: 'toss-error';
        readonly httpStatus: number;
        readonly code: string;
        readonly message: string;
    } | {
        readonly kind: 'transport';
        readonly code: 'NETWORK_ERROR' | 'TIMEOUT';
    };
}

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

Release context

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

구현 주석

시도 1건 = 엔트리 1건 (outcome 유니언) — request/response 분리 kind안은 상관(join) 비용 때문에 기각(설계 §7-7).

⚠ responseBody에는 redaction 후에도 고객 이름·이메일 등 PII가 잔존할 수 있다 — 보관 주체·기간·접근 통제는 sink 소유자(사용자) 책임이다.