/** * Commerce V1 REST 호출 공통 코어. * * stdio(src/commerce)와 Remote(src/commerce-remote) 클라이언트가 같은 코어를 써서 * 같은 입력이면 같은 method·path·header·body 가 나가고, 실패 판정도 같아진다. * Cloudflare Workers 번들에도 들어가므로 Node 전용 API(process, fs 등)를 쓰지 않는다. */ export type CommerceHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; export interface CommerceApiResponse { success: boolean; data?: T; /** 사람이 읽는 오류 메시지. 비밀키·JWT·Authorization 은 가린 뒤의 값 */ error?: string; /** API 가 준 error_code 원문(보통 Code 상수 이름). 응답을 받지 못했으면 UPSTREAM_TIMEOUT 같은 MCP 판정값 */ error_code?: string | number; /** upstream HTTP 상태. 응답 자체를 받지 못했으면 비어 있다 */ http_status?: number; /** * 오류 본문의 payload — commerce-api 가 여기에 벤더(대행사·카카오) 원문 응답을 담아 준다. * 이게 없으면 error_code 만 보고 원인을 추측하게 된다(실측: 발신프로필 등록 3018 의 진짜 사유가 * 여기 있었는데 버려져서, 채널 설정을 하나씩 바꿔 가며 세 번을 헛 호출했다). */ payload?: unknown; /** `${method} ${path}` — query 는 뺀다 */ endpoint?: string; /** * upstream 의 x-request-id. 서버가 500 을 내면서 사유를 아예 안 줄 때(실측: 본문이 * {"error_code":"SERVER_ERROR","message":"Server Error"} 54바이트가 전부) * 서버 로그·Sentry 를 찾아갈 수 있는 유일한 실마리다. */ request_id?: string; /** upstream Retry-After 초: pending 결과·진행 중 멱등 요청의 재조회 간격 */ retry_after?: number; } /** * 회원 본인 API 에서 JWT 대신(또는 함께) 회원을 지정하는 값 — commerce 2026-09-28 계약(MI-00 D1·D4·D6). * GET·DELETE 는 쿼리(`?user_id=`·`?login_id=`), POST·PUT·PATCH 는 JSON 본문(multipart 면 폼 필드)으로 싣는다. * 값은 쇼핑몰 서버 세션에서 꺼낸 것만 넣는다. 개인 식별자라 오류 메시지·payload 에서 가린다. */ export interface CommerceMemberParams { /** 회원 _id(24자리) 또는 가맹점 외부 ID(ex_uid) */ userId?: string; /** 로그인 아이디(l_id). user_id 와 섞지 않는 별도 파라미터 */ loginId?: string; } /** 도구·클라이언트가 한 번에 넘기는 회원 식별: JWT 는 헤더, user_id·login_id 는 쿼리/본문 */ export interface CommerceRequestMember extends CommerceMemberParams { userJwt?: string; } export declare class CommerceMemberParamConflictError extends Error { readonly key: string; constructor(key: string); } /** * 회원 파라미터를 메서드별 위치에 싣는다. * - GET·DELETE: path 쿼리에 URLSearchParams 로 추가(기존 쿼리 유지, 이미 ? 가 있으면 & 로 잇는다) * - POST·PUT·PATCH: 본문(form 이 있으면 폼)에 추가 * 같은 키가 이미 있으면 의미가 모호하므로 CommerceMemberParamConflictError 를 던진다(덮어쓰지 않는다). */ export declare function applyMemberParams(method: CommerceHttpMethod, path: string, options: Pick): { path: string; body?: Record; form?: FormData; }; export interface CommerceRequestOptions { body?: Record; /** * multipart 업로드. 주면 body 대신 이것을 보내고 Content-Type 을 직접 넣지 않는다 * (boundary 는 fetch 가 만든다). 알림톡 템플릿 이미지 업로드가 쓴다. */ form?: FormData; /** Bootpay-User-JWT 헤더로만 보낸다 (URL·본문에 넣지 않는다) */ userJwt?: string; /** Idempotency-Key 헤더로만 보낸다 (본문 업무값이 아니다) */ idempotencyKey?: string; /** 견적·결제 준비·결과 조회에 동일하게 쓰는 게스트 세션 식별자 */ deviceUuid?: string; /** 게스트 결과 조회 bearer. Bootpay-Order-Result-Token 헤더로만 보낸다 */ orderResultToken?: string; /** 회원 지정(user_id·login_id). 메서드별 위치는 applyMemberParams 가 정한다 */ member?: CommerceMemberParams; /** Bootpay-Role 헤더. 게시판 v1 은 supervisor 일 때만 운영자 조회(view=all·비공개 글)를 허용한다 */ role?: 'user' | 'supervisor'; } export interface CommerceTransport { baseUrl: string; authorization: string; /** 오류 메시지에서 가릴 값 (secretKey 등) */ secrets: ReadonlyArray; timeoutMs?: number; } /** 응답이 이 시간 안에 오지 않으면 실패로 돌려준다. 요청이 서버에서 처리됐는지는 알 수 없다 */ export declare const COMMERCE_TIMEOUT_MS = 15000; export declare function basicAuthorization(clientKey: string, secretKey: string): string; export declare function commerceEndpoint(method: CommerceHttpMethod, path: string): string; /** * 오류 문자열에서 비밀값을 가린다. 명시한 값(비밀키·JWT)은 그대로 찾아 지우고, * JWT·견적/결과 토큰 모양·Basic 자격증명·/b 의 __s 세션 값은 모양으로 한 번 더 지운다. */ export declare function maskSecrets(text: string, secrets?: ReadonlyArray): string; /** payload 처럼 구조를 모르는 값 안의 비밀을 가린다. 문자열만 치환하고 모양은 그대로 둔다. */ export declare function maskSecretsDeep(value: unknown, secrets?: ReadonlyArray): unknown; /** * Commerce API 한 번 호출. 다음을 모두 실패(success:false)로 돌려준다. * - HTTP 4xx/5xx, 본문의 error_code(최상위 또는 error.error_code) * - JSON 이 아닌 본문(INVALID_RESPONSE) — HTTP 200 이어도 실패 * - 시간 초과(UPSTREAM_TIMEOUT), 연결 실패(UPSTREAM_UNAVAILABLE) */ export declare function sendCommerceRequest(transport: CommerceTransport, method: CommerceHttpMethod, path: string, options?: CommerceRequestOptions): Promise>; /** * 도구 응답에서 원문과 함께 보존할 Commerce 오류 코드. * API 는 Code 상수 이름(예: ORDER_EXPIRED)을 돌려주고, 옛 응답·문서는 숫자(3770)를 쓴다 — 둘 다 알아본다. */ export declare const COMMERCE_ERROR_CODES: Readonly>; export declare function describeCommerceErrorCode(code: unknown): { error_name?: string; error_number?: number; }; /** * 회원 식별(commerce 2026-09-28 MI 계약) 오류의 사람이 읽는 안내. 해당 없으면 undefined. * -48·131 은 다른 뜻으로도 쓰이므로 payload(reason·field)가 회원 지정일 때만 안내한다. * 안내 문장에 user_id·login_id 원문을 넣지 않는다. */ export declare function describeMemberError(result: Pick): string | undefined; /** * 판매 예약 상품의 구매 거절(10724) 안내. 해당 없으면 undefined. * 에이전트가 "품절"로 잘못 설명하지 않게 판매 시작 전이라는 사실과 다시 시도할 시점을 적는다. */ export declare function describeSaleError(result: Pick): string | undefined; /** 오류 응답에 붙일 공통 필드: 원문 코드, 알려진 이름·숫자, HTTP 상태, 호출한 endpoint, 회원 식별·판매 예약 오류 안내 */ export declare function commerceErrorFields(result: CommerceApiResponse): Record; //# sourceMappingURL=api-core.d.ts.map