import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import { InternalApiClient } from '../client/internal-api.js'; import { StorageApiClient } from '../client/storage-api.js'; import type { LocalImageReader } from '../lib/image-source.js'; import type { ContentBlockInput } from './content-block.js'; /** * save_by 는 Rails 쪽에서 정수 상수와 비교된다(Const::PRODUCT_SAVE_BY_*). * 예전 MCP 는 'save' 문자열을 그대로 보냈는데, `'save' == 3` 이 false 라 * 브랜드 자동생성·배송정책/구독설정 연결 블록이 통째로 스킵됐다. 숫자로 보내는 것이 정답이다. */ export declare const SAVE_BY_PUBLISH = 3; export declare const SAVE_BY_DRAFT = 2; export declare class SaveByError extends Error { } /** 'save'/'draft'/숫자 어느 형태로 들어와도 Rails 상수와 같은 정수로 바꾼다 */ export declare function normalizeSaveBy(value: string | number | undefined | null): number; /** * 서버가 실제로 저장한 save_by. 저장/수정 응답이 그대로 되돌려준다. * 읽지 못하면 undefined — 그때는 저장 상태를 단정하지 않는다. * @date: 26-08-01 */ export declare function extractSavedSaveBy(data: unknown): number | undefined; /** * 저장 상태 보고를 서버가 실제로 저장한 값 기준으로 만든다. * * 요청값으로 "임시저장되었습니다" 를 단정하면, 서버가 save_by 를 반영하지 않는 경우 * 노출되지 않는다고 안내하면서 실제로는 노출되는 사고가 난다(2026-07-31 보고된 증상). * 반대로 "서버가 무시한다" 고 못박아도 서버가 고쳐지면 그때부터 거짓말이 된다. * 그래서 어느 쪽도 단정하지 않고 응답에 실려 온 저장값을 그대로 비교해 알린다. * @date: 26-08-01 */ export declare function buildSaveByReport(requested: number, saved: number | undefined): { fields: Record; notes: string[]; savedAsDraft: boolean; }; /** * update 요청에 실을 stock 을 정한다. * 사용자가 stock 을 명시했으면 그 값이 항상 이긴다 — 추가 조회를 하지 않는다(모든 update 가 2회 호출이 되면 느려진다). * 명시하지 않았으면 현재 값을 읽어 되돌려 보낸다. stock 을 빼고 보내면 서버가 new_stock=nil 로 받아 * stock.rb:83 에서 터지기 때문에, 부분 수정을 살리려면 현재 값을 그대로 실어 보내는 수밖에 없다. * 조회에 실패하거나 저장된 값이 null 이면 0 으로 떨어뜨린다 — 500 을 내는 것보다 낫고, * 이미 stock=null 로 만들어진 상품은 이 경로로 0 이 채워져 정상으로 돌아온다. * @date: 26-08-01 */ export declare function resolveStockForUpdate(internalApi: InternalApiClient, productId: string, stock: number | undefined): Promise; /** * 생성 응답에서 product_id 를 뽑는다. * 서버가 `#` 같은 Ruby 객체 to_s 문자열을 내려주는 경우가 있어 * (직렬화 수정은 internal-api 트랙) 그때는 id 를 뽑을 수 없다 — undefined 를 돌려준다. * @date: 26-08-01 */ export declare function extractCreatedProductId(data: unknown): string | undefined; /** Ruby 객체 문자열(`#`)이면 응답으로 흘리지 않는다 */ export declare function isRubyObjectLeak(data: unknown): boolean; export interface ProductOptionInput { type?: number; name: string[]; keys: string[]; price?: number; tax_free_price?: number; stock?: number; use_stock?: boolean; sku?: string; status?: number; img?: string[]; } export interface SubscriptionPeriodInput { label?: string; duration: number; duration_type?: number; display_price: number; cost_price?: number; tax_free_price?: number; use_discount?: boolean; discount_price?: number; discount_price_type?: number; default_field?: boolean; } /** * 스키마에 있는 이름이 서버 필드 이름과 같아 그대로 실어 보내는 키. * * 이 배열이 곧 허용 목록이다 — 스키마에만 추가하고 여기 빠뜨리면 값이 조용히 사라진다(D-1 과 같은 사고). * 반대로 여기에만 넣고 스키마에 없으면 모델이 보낼 방법이 없다. 둘은 항상 같이 고친다. */ export declare const PASSTHROUGH_PRODUCT_KEYS: readonly ["tax_type", "vat_display_type", "use_display_period", "display_start_at", "display_end_at", "use_sale_period", "sale_start_at", "sale_end_at", "use_discount_period", "discount_start_at", "discount_end_at", "status_time_sale", "time_sale_start_at", "time_sale_end_at", "time_sale_discount_percent", "use_accumulation", "accumulation_point", "accumulation_point_type", "use_stock_safe", "stock_safe", "use_setup_fee", "setup_fee_value", "setup_fee_type", "setup_fee_text", "barcode", "use_seo", "seo_page_title", "seo_meta_description", "seo_meta_tags", "search_tags", "event_tags", "target_user_tags", "delivery_tags", "emotion_tags", "use_coupon", "use_member_discount", "use_minor", "use_free_gift", "free_gift", "use_give_gift", "use_like", "use_review", "use_display_stock", "use_able_refund", "use_able_cart", "use_product_option", "use_additional_option", "use_custom", "use_display_price", "display_min_price", "use_migrate_plan", "use_migrate_plan_approval", "migration_candidate_ids"]; /** 시작만 보낸 판매기간(판매 예약) — 호출처가 플래그를 채우고 결과 note 를 만든다 */ export type SaleReservation = { /** 보낸 그대로의 시작 시각 */ startAt: string; /** use_sale_period 를 보내지 않아 도구가 true 로 채워야 하는지 */ flagAdded: boolean; /** update 에서 sale_end_at: null 로 종료를 지웠는지 */ endCleared: boolean; /** 시작이 이미 지났는지 */ past: boolean; }; /** * 판매 예약 결과 안내 한 줄. * * update 에서 종료를 보내지 않았다면 기존 종료가 남아 있을 수 있으므로 "종료 없음"이라고 단정하지 않는다. */ export declare function saleReservationNote(reservation: SaleReservation, mode: 'create' | 'update'): string; /** * 기간 짝 검증. * * 서버는 시작·종료 중 하나만 오면 **둘 다 nil 로 만든다**(create.rb `_compact_data`). * 저장은 성공하고 기간만 사라지므로, 그 전에 도구가 막아 원인을 알려준다. * * 판매기간은 예외다(endOptional) — 시작만 보내면 판매 예약으로 통과시키고 `reservation` 을 돌려준다. * 종료만 보낸 경우와 `use_sale_period: false` 를 명시한 경우는 거절한다. 시작이 이미 지났으면 경고만 붙인다 * (관리자 자세히 화면의 과거 시각 정책과 같다). update 의 `sale_end_at: null` 은 "종료 지우기"다. * * mode='update' 에서는 플래그 짝 어긋남을 경고로 낮춘다 — 이미 저장된 상품이 반대쪽 값을 * 가지고 있을 수 있어(기간만 고치는 수정, 플래그만 켜는 수정) 거절하면 정상 수정이 막힌다. */ export declare function validateSalePeriods(params: Record, mode?: 'create' | 'update', now?: number): { error: string | null; warnings: string[]; reservation?: SaleReservation; }; /** * `use_*` 플래그와 값의 짝 검증. * * 플래그를 명시적으로 false 로 보내면서 값을 함께 보내는 것은 어느 모드에서든 모순이라 거절한다. * 플래그를 아예 안 보낸 경우는 생성에서만 거절한다 — 수정은 상품에 이미 켜져 있을 수 있다. */ export declare function validateFlagPairs(params: Record, mode?: 'create' | 'update'): { error: string | null; warnings: string[]; }; /** * 상세 이미지를 보냈는데 상세설명 방식이 이미지가 아닐 때의 경고. * * 값은 content_images 로 저장되지만, 상품 상세는 content(HTML/블록 컴파일 결과)를 먼저 렌더하고 * 그것이 비었을 때만 이미지를 쓴다. 즉 블록·HTML 로 상세를 채우면서 상세 이미지를 함께 보내면 * 그 이미지는 상품 페이지에 나오지 않는다 — 저장은 됐으니 오류가 아니고, 조용히 두면 안 되니 경고다. * @date: 2026-08-10 */ export declare function detailImagesNote(params: { detail_images?: string[]; content?: string; content_type?: number; content_blocks?: ContentBlockInput[]; }, mode?: 'create' | 'update'): string | null; /** 구독·배송 입력의 앞단 검증. 반환값이 있으면 그대로 오류로 돌려주면 된다. */ export declare function validateSubscriptionDelivery(params: { use_subscription?: boolean; subscription_setting_id?: string; use_subscription_times?: boolean; subscription_periods?: SubscriptionPeriodInput[]; use_delivery_shipping?: boolean; delivery_shipping_id?: string; use_delivery_shipping_bundle?: boolean; delivery_shipping_bundle_id?: string; save_by?: number; }): string | null; export declare function describeProductError(error: unknown): string; export declare function registerProductTools(server: McpServer, internalApi: InternalApiClient, storageApi: StorageApiClient, opts?: { readLocalFile?: LocalImageReader; }): void; //# sourceMappingURL=product.d.ts.map