@crmforall/connector 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,314 @@
+import { z } from "zod";
+/**
+ * 커넥터 런타임 설정.
+ * 위치: $CRMFORALL_CONFIG 또는 ~/.crmforall/connector.json (0600).
+ * 보안 원칙: DB 비밀번호·커넥터 시크릿은 이 파일과 환경변수로만 흐른다.
+ * AI 운전 계층(MCP 호출자)에게는 어떤 도구 출력에도 노출하지 않는다.
+ */
+export declare const fieldMappingEntitySchema: z.ZodObject<{
+    table: z.ZodObject<{
+        schema: z.ZodString;
+        table: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        table: string;
+        schema: string;
+    }, {
+        table: string;
+        schema: string;
+    }>;
+    /** 표준 필드명 → 운영 DB 컬럼명 */
+    fields: z.ZodRecord<z.ZodString, z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    table: {
+        table: string;
+        schema: string;
+    };
+    fields: Record<string, string>;
+}, {
+    table: {
+        table: string;
+        schema: string;
+    };
+    fields: Record<string, string>;
+}>;
+export type FieldMappingEntity = z.infer<typeof fieldMappingEntitySchema>;
+export declare const mappingConfigSchema: z.ZodObject<{
+    version: z.ZodString;
+    customer: z.ZodObject<{
+        table: z.ZodObject<{
+            schema: z.ZodString;
+            table: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            table: string;
+            schema: string;
+        }, {
+            table: string;
+            schema: string;
+        }>;
+        /** 표준 필드명 → 운영 DB 컬럼명 */
+        fields: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        table: {
+            table: string;
+            schema: string;
+        };
+        fields: Record<string, string>;
+    }, {
+        table: {
+            table: string;
+            schema: string;
+        };
+        fields: Record<string, string>;
+    }>;
+    reservation: z.ZodObject<{
+        table: z.ZodObject<{
+            schema: z.ZodString;
+            table: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            table: string;
+            schema: string;
+        }, {
+            table: string;
+            schema: string;
+        }>;
+        /** 표준 필드명 → 운영 DB 컬럼명 */
+        fields: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        table: {
+            table: string;
+            schema: string;
+        };
+        fields: Record<string, string>;
+    }, {
+        table: {
+            table: string;
+            schema: string;
+        };
+        fields: Record<string, string>;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    customer: {
+        table: {
+            table: string;
+            schema: string;
+        };
+        fields: Record<string, string>;
+    };
+    reservation: {
+        table: {
+            table: string;
+            schema: string;
+        };
+        fields: Record<string, string>;
+    };
+}, {
+    version: string;
+    customer: {
+        table: {
+            table: string;
+            schema: string;
+        };
+        fields: Record<string, string>;
+    };
+    reservation: {
+        table: {
+            table: string;
+            schema: string;
+        };
+        fields: Record<string, string>;
+    };
+}>;
+export type MappingConfig = z.infer<typeof mappingConfigSchema>;
+export declare const connectorConfigSchema: z.ZodObject<{
+    platformUrl: z.ZodString;
+    tenantId: z.ZodString;
+    connectionId: z.ZodString;
+    connectorId: z.ZodString;
+    /** 플랫폼 인증 시크릿 — 설치 토큰 교환으로 발급됨 */
+    connectorSecret: z.ZodString;
+    crmSchema: z.ZodDefault<z.ZodString>;
+    db: z.ZodObject<{
+        sourceType: z.ZodEnum<["postgresql", "mysql", "supabase", "cafe24"]>;
+        host: z.ZodString;
+        port: z.ZodNumber;
+        database: z.ZodString;
+        user: z.ZodString;
+        password: z.ZodString;
+        ssl: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        sourceType: "postgresql" | "mysql" | "supabase" | "cafe24";
+        host: string;
+        port: number;
+        database: string;
+        user: string;
+        password: string;
+        ssl: boolean;
+    }, {
+        sourceType: "postgresql" | "mysql" | "supabase" | "cafe24";
+        host: string;
+        port: number;
+        database: string;
+        user: string;
+        password: string;
+        ssl?: boolean | undefined;
+    }>;
+    /** 확정된 표준 필드 매핑 — validate_mapping 통과본만 저장 */
+    mapping: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        version: z.ZodString;
+        customer: z.ZodObject<{
+            table: z.ZodObject<{
+                schema: z.ZodString;
+                table: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                table: string;
+                schema: string;
+            }, {
+                table: string;
+                schema: string;
+            }>;
+            /** 표준 필드명 → 운영 DB 컬럼명 */
+            fields: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            table: {
+                table: string;
+                schema: string;
+            };
+            fields: Record<string, string>;
+        }, {
+            table: {
+                table: string;
+                schema: string;
+            };
+            fields: Record<string, string>;
+        }>;
+        reservation: z.ZodObject<{
+            table: z.ZodObject<{
+                schema: z.ZodString;
+                table: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                table: string;
+                schema: string;
+            }, {
+                table: string;
+                schema: string;
+            }>;
+            /** 표준 필드명 → 운영 DB 컬럼명 */
+            fields: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            table: {
+                table: string;
+                schema: string;
+            };
+            fields: Record<string, string>;
+        }, {
+            table: {
+                table: string;
+                schema: string;
+            };
+            fields: Record<string, string>;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        customer: {
+            table: {
+                table: string;
+                schema: string;
+            };
+            fields: Record<string, string>;
+        };
+        reservation: {
+            table: {
+                table: string;
+                schema: string;
+            };
+            fields: Record<string, string>;
+        };
+    }, {
+        version: string;
+        customer: {
+            table: {
+                table: string;
+                schema: string;
+            };
+            fields: Record<string, string>;
+        };
+        reservation: {
+            table: {
+                table: string;
+                schema: string;
+            };
+            fields: Record<string, string>;
+        };
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    platformUrl: string;
+    tenantId: string;
+    connectionId: string;
+    connectorId: string;
+    connectorSecret: string;
+    crmSchema: string;
+    db: {
+        sourceType: "postgresql" | "mysql" | "supabase" | "cafe24";
+        host: string;
+        port: number;
+        database: string;
+        user: string;
+        password: string;
+        ssl: boolean;
+    };
+    mapping: {
+        version: string;
+        customer: {
+            table: {
+                table: string;
+                schema: string;
+            };
+            fields: Record<string, string>;
+        };
+        reservation: {
+            table: {
+                table: string;
+                schema: string;
+            };
+            fields: Record<string, string>;
+        };
+    } | null;
+}, {
+    platformUrl: string;
+    tenantId: string;
+    connectionId: string;
+    connectorId: string;
+    connectorSecret: string;
+    db: {
+        sourceType: "postgresql" | "mysql" | "supabase" | "cafe24";
+        host: string;
+        port: number;
+        database: string;
+        user: string;
+        password: string;
+        ssl?: boolean | undefined;
+    };
+    crmSchema?: string | undefined;
+    mapping?: {
+        version: string;
+        customer: {
+            table: {
+                table: string;
+                schema: string;
+            };
+            fields: Record<string, string>;
+        };
+        reservation: {
+            table: {
+                table: string;
+                schema: string;
+            };
+            fields: Record<string, string>;
+        };
+    } | null | undefined;
+}>;
+export type ConnectorConfig = z.infer<typeof connectorConfigSchema>;
+export declare function defaultConfigPath(): string;
+export declare function loadConfig(path?: string): ConnectorConfig | null;
+export declare function saveConfig(config: ConnectorConfig, path?: string): void;

package/dist/config.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectorConfigSchema = exports.mappingConfigSchema = exports.fieldMappingEntitySchema = void 0;
+exports.defaultConfigPath = defaultConfigPath;
+exports.loadConfig = loadConfig;
+exports.saveConfig = saveConfig;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const zod_1 = require("zod");
+/**
+ * 커넥터 런타임 설정.
+ * 위치: $CRMFORALL_CONFIG 또는 ~/.crmforall/connector.json (0600).
+ * 보안 원칙: DB 비밀번호·커넥터 시크릿은 이 파일과 환경변수로만 흐른다.
+ * AI 운전 계층(MCP 호출자)에게는 어떤 도구 출력에도 노출하지 않는다.
+ */
+exports.fieldMappingEntitySchema = zod_1.z.object({
+    table: zod_1.z.object({
+        schema: zod_1.z.string().min(1),
+        table: zod_1.z.string().min(1),
+    }),
+    /** 표준 필드명 → 운영 DB 컬럼명 */
+    fields: zod_1.z.record(zod_1.z.string(), zod_1.z.string()),
+});
+exports.mappingConfigSchema = zod_1.z.object({
+    version: zod_1.z.string().min(1),
+    customer: exports.fieldMappingEntitySchema,
+    reservation: exports.fieldMappingEntitySchema,
+});
+exports.connectorConfigSchema = zod_1.z.object({
+    platformUrl: zod_1.z.string().url(),
+    tenantId: zod_1.z.string().min(1),
+    connectionId: zod_1.z.string().min(1),
+    connectorId: zod_1.z.string().min(1),
+    /** 플랫폼 인증 시크릿 — 설치 토큰 교환으로 발급됨 */
+    connectorSecret: zod_1.z.string().min(16),
+    crmSchema: zod_1.z
+        .string()
+        .regex(/^[a-z_][a-z0-9_]{0,62}$/)
+        .default("crmforall"),
+    db: zod_1.z.object({
+        sourceType: zod_1.z.enum(["postgresql", "mysql", "supabase", "cafe24"]),
+        host: zod_1.z.string().min(1),
+        port: zod_1.z.number().int().positive(),
+        database: zod_1.z.string().min(1),
+        user: zod_1.z.string().min(1),
+        password: zod_1.z.string().min(1),
+        ssl: zod_1.z.boolean().default(false),
+    }),
+    /** 확정된 표준 필드 매핑 — validate_mapping 통과본만 저장 */
+    mapping: exports.mappingConfigSchema.nullable().default(null),
+});
+function defaultConfigPath() {
+    return (process.env.CRMFORALL_CONFIG ?? (0, node_path_1.join)((0, node_os_1.homedir)(), ".crmforall", "connector.json"));
+}
+function loadConfig(path = defaultConfigPath()) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    const raw = JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+    // 환경변수가 파일보다 우선 (컨테이너/Secrets Manager 주입 경로)
+    if (process.env.CRMFORALL_DB_PASSWORD) {
+        raw.db = { ...raw.db, password: process.env.CRMFORALL_DB_PASSWORD };
+    }
+    if (process.env.CRMFORALL_CONNECTOR_SECRET) {
+        raw.connectorSecret = process.env.CRMFORALL_CONNECTOR_SECRET;
+    }
+    return exports.connectorConfigSchema.parse(raw);
+}
+function saveConfig(config, path = defaultConfigPath()) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+    (0, node_fs_1.writeFileSync)(path, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+}

package/dist/contracts.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @crmforall/contracts 미러 (커넥터에 필요한 부분만).
+ * TODO: contracts 패키지 npm 발행 후 이 파일을 의존성으로 교체한다.
+ * 원본: crmforall-platform/packages/contracts/src/{mcp-tools,approval,errors,standard-fields}.ts
+ */
+export declare const MCP_TOOL: {
+    readonly TEST_CONNECTION: "test_connection";
+    readonly INSPECT_SCHEMA: "inspect_schema";
+    readonly PROPOSE_FIELD_MAPPING: "propose_field_mapping";
+    readonly VALIDATE_MAPPING: "validate_mapping";
+    readonly PREVIEW_TARGETS: "preview_targets";
+    readonly CREATE_TARGET_SNAPSHOT: "create_target_snapshot";
+    readonly WRITE_CRM_EVENT: "write_crm_event";
+    readonly SEND_KAKAO_MESSAGE: "send_kakao_message";
+    readonly SYNC_SEND_RESULT: "sync_send_result";
+    readonly IMPORT_PROSPECTS: "import_prospects";
+    readonly REGISTER_ENTRY_POINT: "register_entry_point";
+    readonly TRACK_ENGAGEMENT: "track_engagement";
+};
+export type McpToolName = (typeof MCP_TOOL)[keyof typeof MCP_TOOL];
+export declare const APPROVAL_SCOPE: {
+    readonly TARGET_SNAPSHOT_CREATE: "target_snapshot:create";
+    readonly CRM_EVENT_WRITE: "crm_event:write";
+    readonly KAKAO_SEND: "kakao:send";
+    readonly PROSPECT_IMPORT: "prospect:import";
+    readonly ENTRY_POINT_REGISTER: "entry_point:register";
+};
+export type ApprovalScope = (typeof APPROVAL_SCOPE)[keyof typeof APPROVAL_SCOPE];
+/** 도구별 필요 승인 scope. null = 승인 불필요. */
+export declare const TOOL_APPROVAL_REQUIREMENT: Record<McpToolName, ApprovalScope | null>;
+/** 승인 토큰이 필요한 도구 — 토큰 없이 호출되면 즉시 거부한다. */
+export declare const APPROVAL_REQUIRED_TOOLS: ReadonlySet<McpToolName>;
+export declare const ERROR_CODE: {
+    readonly NET_UNREACHABLE: "E_NET_UNREACHABLE";
+    readonly AUTH_FAILED: "E_AUTH_FAILED";
+    readonly OVERPRIVILEGED: "E_OVERPRIVILEGED";
+    readonly SCHEMA_MISSING_FIELD: "E_SCHEMA_MISSING_FIELD";
+    readonly TOKEN_EXPIRED: "E_TOKEN_EXPIRED";
+    readonly TOKEN_REUSED: "E_TOKEN_REUSED";
+    readonly TOKEN_SCOPE_MISMATCH: "E_TOKEN_SCOPE_MISMATCH";
+    readonly SNAPSHOT_HASH_MISMATCH: "E_SNAPSHOT_HASH_MISMATCH";
+    readonly CONSENT_AMBIGUOUS: "E_CONSENT_AMBIGUOUS";
+    readonly CRM_SCHEMA_NOT_READY: "E_CRM_SCHEMA_NOT_READY";
+    readonly PLATFORM_UNREACHABLE: "E_PLATFORM_UNREACHABLE";
+};
+export type ErrorCode = (typeof ERROR_CODE)[keyof typeof ERROR_CODE];
+export declare const ERROR_HINTS: Record<ErrorCode, string>;
+/** 필수 표준 필드 — 전부 매핑돼야 조건 프로젝트 활성화 가능 (기존 수용 기준) */
+export declare const REQUIRED_MAPPING_FIELDS: readonly ["customerKey", "phoneNumberHash", "marketingOptIn", "reservationId", "productId", "pickupCompletedAt"];
+export type RequiredMappingField = (typeof REQUIRED_MAPPING_FIELDS)[number];
+/** preview_targets 제외 사유 — 원문 전화번호 미노출, 사유별 건수만 */
+export declare const EXCLUSION_REASON: {
+    readonly CHANNEL_BLOCKED: "channel_blocked";
+    readonly UNSUBSCRIBED: "unsubscribed";
+    readonly MARKETING_OPT_OUT: "marketing_opt_out";
+    readonly PHONE_MISSING: "phone_missing";
+    readonly DUPLICATE: "duplicate";
+    readonly RECENT_SEND_LIMIT: "recent_send_limit";
+    readonly CONSENT_AMBIGUOUS: "consent_ambiguous";
+};
+export type ExclusionReason = (typeof EXCLUSION_REASON)[keyof typeof EXCLUSION_REASON];

package/dist/contracts.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXCLUSION_REASON = exports.REQUIRED_MAPPING_FIELDS = exports.ERROR_HINTS = exports.ERROR_CODE = exports.APPROVAL_REQUIRED_TOOLS = exports.TOOL_APPROVAL_REQUIREMENT = exports.APPROVAL_SCOPE = exports.MCP_TOOL = void 0;
+/**
+ * @crmforall/contracts 미러 (커넥터에 필요한 부분만).
+ * TODO: contracts 패키지 npm 발행 후 이 파일을 의존성으로 교체한다.
+ * 원본: crmforall-platform/packages/contracts/src/{mcp-tools,approval,errors,standard-fields}.ts
+ */
+exports.MCP_TOOL = {
+    TEST_CONNECTION: "test_connection",
+    INSPECT_SCHEMA: "inspect_schema",
+    PROPOSE_FIELD_MAPPING: "propose_field_mapping",
+    VALIDATE_MAPPING: "validate_mapping",
+    PREVIEW_TARGETS: "preview_targets",
+    CREATE_TARGET_SNAPSHOT: "create_target_snapshot",
+    WRITE_CRM_EVENT: "write_crm_event",
+    SEND_KAKAO_MESSAGE: "send_kakao_message",
+    SYNC_SEND_RESULT: "sync_send_result",
+    IMPORT_PROSPECTS: "import_prospects",
+    REGISTER_ENTRY_POINT: "register_entry_point",
+    TRACK_ENGAGEMENT: "track_engagement",
+};
+exports.APPROVAL_SCOPE = {
+    TARGET_SNAPSHOT_CREATE: "target_snapshot:create",
+    CRM_EVENT_WRITE: "crm_event:write",
+    KAKAO_SEND: "kakao:send",
+    PROSPECT_IMPORT: "prospect:import",
+    ENTRY_POINT_REGISTER: "entry_point:register",
+};
+/** 도구별 필요 승인 scope. null = 승인 불필요. */
+exports.TOOL_APPROVAL_REQUIREMENT = {
+    [exports.MCP_TOOL.TEST_CONNECTION]: null,
+    [exports.MCP_TOOL.INSPECT_SCHEMA]: null,
+    [exports.MCP_TOOL.PROPOSE_FIELD_MAPPING]: null,
+    [exports.MCP_TOOL.VALIDATE_MAPPING]: null,
+    [exports.MCP_TOOL.PREVIEW_TARGETS]: null,
+    [exports.MCP_TOOL.CREATE_TARGET_SNAPSHOT]: exports.APPROVAL_SCOPE.TARGET_SNAPSHOT_CREATE,
+    [exports.MCP_TOOL.WRITE_CRM_EVENT]: exports.APPROVAL_SCOPE.CRM_EVENT_WRITE,
+    [exports.MCP_TOOL.SEND_KAKAO_MESSAGE]: exports.APPROVAL_SCOPE.KAKAO_SEND,
+    [exports.MCP_TOOL.SYNC_SEND_RESULT]: null,
+    [exports.MCP_TOOL.IMPORT_PROSPECTS]: exports.APPROVAL_SCOPE.PROSPECT_IMPORT,
+    [exports.MCP_TOOL.REGISTER_ENTRY_POINT]: exports.APPROVAL_SCOPE.ENTRY_POINT_REGISTER,
+    [exports.MCP_TOOL.TRACK_ENGAGEMENT]: null,
+};
+/** 승인 토큰이 필요한 도구 — 토큰 없이 호출되면 즉시 거부한다. */
+exports.APPROVAL_REQUIRED_TOOLS = new Set(Object.entries(exports.TOOL_APPROVAL_REQUIREMENT)
+    .filter(([, scope]) => scope !== null)
+    .map(([name]) => name));
+exports.ERROR_CODE = {
+    NET_UNREACHABLE: "E_NET_UNREACHABLE",
+    AUTH_FAILED: "E_AUTH_FAILED",
+    OVERPRIVILEGED: "E_OVERPRIVILEGED",
+    SCHEMA_MISSING_FIELD: "E_SCHEMA_MISSING_FIELD",
+    TOKEN_EXPIRED: "E_TOKEN_EXPIRED",
+    TOKEN_REUSED: "E_TOKEN_REUSED",
+    TOKEN_SCOPE_MISMATCH: "E_TOKEN_SCOPE_MISMATCH",
+    SNAPSHOT_HASH_MISMATCH: "E_SNAPSHOT_HASH_MISMATCH",
+    CONSENT_AMBIGUOUS: "E_CONSENT_AMBIGUOUS",
+    CRM_SCHEMA_NOT_READY: "E_CRM_SCHEMA_NOT_READY",
+    PLATFORM_UNREACHABLE: "E_PLATFORM_UNREACHABLE",
+};
+exports.ERROR_HINTS = {
+    [exports.ERROR_CODE.NET_UNREACHABLE]: "DB 호스트에 도달할 수 없습니다. 방화벽/보안그룹에서 DB 포트의 아웃바운드 허용 여부를 확인하세요.",
+    [exports.ERROR_CODE.AUTH_FAILED]: "인증에 실패했습니다. 자격증명과 계정 잠금 여부를 확인하세요.",
+    [exports.ERROR_CODE.OVERPRIVILEGED]: "과권한 계정이 감지되었습니다. 출력된 권한 축소 SQL을 실행한 뒤 connect doctor를 다시 실행하세요. 과권한 상태에서는 활성화가 차단됩니다.",
+    [exports.ERROR_CODE.SCHEMA_MISSING_FIELD]: "필수 표준 필드가 매핑되지 않았습니다. propose_field_mapping을 실행하세요.",
+    [exports.ERROR_CODE.TOKEN_EXPIRED]: "토큰이 만료되었습니다. 웹 콘솔에서 재발급 받으세요.",
+    [exports.ERROR_CODE.TOKEN_REUSED]: "이미 사용된 승인 토큰입니다. 새 승인을 요청하세요.",
+    [exports.ERROR_CODE.TOKEN_SCOPE_MISMATCH]: "승인 토큰의 scope가 요청 작업과 일치하지 않습니다.",
+    [exports.ERROR_CODE.SNAPSHOT_HASH_MISMATCH]: "승인된 대상 스냅샷과 실행 대상이 다릅니다. 대상을 다시 산출하고 재승인 받으세요.",
+    [exports.ERROR_CODE.CONSENT_AMBIGUOUS]: "광고성 수신동의 또는 채널 상태가 불명확한 대상이 포함되어 발송이 차단되었습니다(fail-closed). 해당 대상은 제외 사유에 표시됩니다.",
+    [exports.ERROR_CODE.CRM_SCHEMA_NOT_READY]: "CRM 전용 스키마가 없거나 마이그레이션이 필요합니다. connect init 또는 connect upgrade를 실행하세요.",
+    [exports.ERROR_CODE.PLATFORM_UNREACHABLE]: "crmforall 플랫폼에 연결할 수 없습니다. 네트워크와 설치 토큰 상태를 확인하세요.",
+};
+/** 필수 표준 필드 — 전부 매핑돼야 조건 프로젝트 활성화 가능 (기존 수용 기준) */
+exports.REQUIRED_MAPPING_FIELDS = [
+    "customerKey",
+    "phoneNumberHash",
+    "marketingOptIn",
+    "reservationId",
+    "productId",
+    "pickupCompletedAt",
+];
+/** preview_targets 제외 사유 — 원문 전화번호 미노출, 사유별 건수만 */
+exports.EXCLUSION_REASON = {
+    CHANNEL_BLOCKED: "channel_blocked",
+    UNSUBSCRIBED: "unsubscribed",
+    MARKETING_OPT_OUT: "marketing_opt_out",
+    PHONE_MISSING: "phone_missing",
+    DUPLICATE: "duplicate",
+    RECENT_SEND_LIMIT: "recent_send_limit",
+    CONSENT_AMBIGUOUS: "consent_ambiguous",
+};

package/dist/db/adapter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * DB 어댑터 인터페이스 — PostgreSQL/MySQL/Supabase/카페24가 모두 이 계약을 구현한다.
+ * 근거: 마스터플랜 04_MCP_Connector §지원 데이터 소스, §Connection Readiness Gate.
+ */
+export interface ColumnInfo {
+    schema: string;
+    table: string;
+    column: string;
+    dataType: string;
+}
+/** Readiness 검사 항목별 결과 */
+export interface ReadinessCheck {
+    name: "connect" | "operational_select" | "crm_schema_exists" | "crm_schema_write" | "source_table_write_blocked" | "ddl_limited";
+    passed: boolean;
+    detail: string;
+    /** 과권한 감지 시 권한 축소 SQL 제안 (DBA 전달용) */
+    remediationSql?: string;
+}
+export interface ReadinessReport {
+    ready: boolean;
+    /** 과권한 감지 — true면 활성화 차단 (fail-closed) */
+    overprivileged: boolean;
+    checks: ReadinessCheck[];
+}
+/**
+ * SQL 직접 실행 능력 — 대상 산출(읽기)과 CRM 스키마 쓰기의 기반.
+ * selectRows는 읽기 전용 쿼리만, execute는 CRM 전용 스키마 쓰기만 받는다.
+ * (운영 원천 테이블 쓰기는 Readiness Gate에서 권한 자체를 차단한다)
+ */
+export interface SqlExecutor {
+    selectRows(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+    execute(sql: string, params?: unknown[]): Promise<{
+        rowCount: number;
+    }>;
+}
+export interface DbAdapter extends SqlExecutor {
+    readonly sourceType: "postgresql" | "mysql" | "supabase" | "cafe24";
+    /** 연결 시도 — 자격증명은 어댑터 생성 시 시크릿 저장소에서 주입된다 */
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * Connection Readiness Gate 일괄 검사.
+     * 핵심: 운영 원천 테이블에 쓰기 권한이 있으면 overprivileged=true로
+     * 활성화를 차단해야 한다 (기존 SPEC 계승).
+     */
+    checkReadiness(options: {
+        crmSchema: string;
+    }): Promise<ReadinessReport>;
+    /** 스키마 탐색 — 컬럼명 중심, 데이터 미노출 (inspect_schema 도구의 기반) */
+    listColumns(options: {
+        schemaAllowlist?: string[];
+    }): Promise<ColumnInfo[]>;
+    /** CRM 전용 스키마 생성/마이그레이션 (멱등) — 설치 단계에만 호출 */
+    ensureCrmSchema(options: {
+        crmSchema: string;
+    }): Promise<void>;
+}

package/dist/db/adapter.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * DB 어댑터 인터페이스 — PostgreSQL/MySQL/Supabase/카페24가 모두 이 계약을 구현한다.
+ * 근거: 마스터플랜 04_MCP_Connector §지원 데이터 소스, §Connection Readiness Gate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/db/crm-schema.d.ts

@@ -0,0 +1,9 @@
+import type { SqlExecutor } from "./adapter";
+/**
+ * CRM 전용 스키마 DDL — 멱등 (CREATE TABLE IF NOT EXISTS).
+ * 근거: 01_데이터_모델 §고객사 측 CRM 스키마 (기존 9테이블 중 MVP 사용분).
+ * 구조는 고객사 DB든 관리형 테넌트 스키마든 동일해야 한다 (내보내기 보장의 기반).
+ * 호출 시점: 설치 단계(connect init)에만 — DDL 권한은 설치 시에만 허용된다.
+ */
+export declare function validateSchemaName(crmSchema: string): void;
+export declare function migrateCrmSchema(db: SqlExecutor, crmSchema: string): Promise<void>;