@crmforall/connector 0.1.0

package/dist/platform.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpPlatformClient = exports.PlatformError = void 0;
+const contracts_1 = require("./contracts");
+class PlatformError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "PlatformError";
+    }
+}
+exports.PlatformError = PlatformError;
+class HttpPlatformClient {
+    opts;
+    fetchImpl;
+    constructor(opts) {
+        this.opts = opts;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    async request(method, path, body) {
+        let res;
+        try {
+            res = await this.fetchImpl(new URL(path, this.opts.platformUrl), {
+                method,
+                headers: {
+                    "content-type": "application/json",
+                    "x-connector-id": this.opts.connectorId,
+                    authorization: `Bearer ${this.opts.connectorSecret}`,
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw new PlatformError(contracts_1.ERROR_CODE.PLATFORM_UNREACHABLE, `플랫폼 요청 실패: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (res.status === 401 || res.status === 403) {
+            throw new PlatformError(contracts_1.ERROR_CODE.AUTH_FAILED, "커넥터 자격증명이 거부되었습니다. connect init으로 재등록하세요.");
+        }
+        const json = (await res.json().catch(() => null));
+        if (!res.ok) {
+            throw new PlatformError(json?.error?.code ?? contracts_1.ERROR_CODE.PLATFORM_UNREACHABLE, json?.error?.message ?? `플랫폼 응답 오류 (HTTP ${res.status})`);
+        }
+        return json;
+    }
+    async consumeApproval(input) {
+        // consume은 거부 사유를 에러가 아닌 결과로 받는다 — 도구가 코드별 힌트를 내보내야 하므로
+        try {
+            const data = await this.request("POST", "/api/approvals/consume", {
+                token: input.token,
+                expectedScope: input.expectedScope,
+                snapshotHash: input.snapshotHash ?? null,
+            });
+            if (data.ok && data.claims)
+                return { ok: true, claims: data.claims };
+            return {
+                ok: false,
+                code: data.error?.code ?? contracts_1.ERROR_CODE.AUTH_FAILED,
+                message: data.error?.message ?? "승인 토큰 검증 실패",
+            };
+        }
+        catch (err) {
+            if (err instanceof PlatformError) {
+                return { ok: false, code: err.code, message: err.message };
+            }
+            throw err;
+        }
+    }
+    async getProjectDefinition(projectId) {
+        const data = await this.request("GET", `/api/projects/${encodeURIComponent(projectId)}/definition`);
+        return data.project;
+    }
+    async reportEngagement(input) {
+        await this.request("POST", "/api/engagements", input);
+    }
+    async createSendJob(input) {
+        const data = await this.request("POST", "/api/sends", input);
+        return { sendJobId: data.sendJobId };
+    }
+    async getSendJob(sendJobId) {
+        const data = await this.request("GET", `/api/sends/${encodeURIComponent(sendJobId)}`);
+        return data.job;
+    }
+}
+exports.HttpPlatformClient = HttpPlatformClient;

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const config_1 = require("./config");
+const index_1 = require("./index");
+const platform_1 = require("./platform");
+const tools_1 = require("./tools");
+/**
+ * crmforall MCP 커넥터 서버 (stdio).
+ * 설정은 connect init이 만든 ~/.crmforall/connector.json에서 읽는다.
+ * 자격증명은 도구 출력 어디에도 노출되지 않는다 (AI 비노출 원칙).
+ */
+async function main() {
+    const config = (0, config_1.loadConfig)();
+    if (!config) {
+        console.error("[crmforall-connector] 설정이 없습니다. 먼저 `npx @crmforall/connect init`을 실행하세요.");
+        process.exit(1);
+    }
+    let db = null;
+    const getDb = async () => {
+        if (!db) {
+            const adapter = (0, index_1.buildAdapter)(config);
+            await adapter.connect();
+            db = adapter;
+        }
+        return db;
+    };
+    const server = new mcp_js_1.McpServer({
+        name: "crmforall-connector",
+        version: "0.1.0",
+    });
+    (0, tools_1.registerTools)(server, {
+        config,
+        platform: new platform_1.HttpPlatformClient({
+            platformUrl: config.platformUrl,
+            connectorId: config.connectorId,
+            connectorSecret: config.connectorSecret,
+        }),
+        getDb,
+        persistMapping: async (mapping) => {
+            config.mapping = mapping;
+            (0, config_1.saveConfig)(config);
+        },
+    });
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("[crmforall-connector] MCP 서버 시작 (stdio)");
+    const shutdown = async () => {
+        await db?.disconnect().catch(() => { });
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((err) => {
+    console.error("[crmforall-connector] 시작 실패:", err);
+    process.exit(1);
+});

package/dist/targets.d.ts

@@ -0,0 +1,40 @@
+import type { SqlExecutor } from "./db/adapter";
+import type { MappingConfig } from "./config";
+import { type ExclusionReason } from "./contracts";
+import type { ProjectDefinition } from "./platform";
+/**
+ * 대상 산출 — preview_targets / create_target_snapshot의 공용 계산.
+ *
+ * fail-closed 원칙 (기존 SPEC §카카오 발송 어댑터):
+ * 광고성 수신동의·채널 상태 중 하나라도 누락/불명확하면 브랜드 메시지(광고) 대상에서 제외한다.
+ * 제외는 사유별 건수로만 보고한다 — 원문 전화번호는 이 계층을 통과하지 않는다.
+ */
+export interface TargetMember {
+    customerKey: string;
+    phoneHash: string;
+}
+export interface TargetComputation {
+    members: TargetMember[];
+    exclusions: Array<{
+        reason: ExclusionReason;
+        count: number;
+    }>;
+    previewHash: string;
+}
+/**
+ * 스냅샷/미리보기 해시 — 같은 대상 집합이면 항상 같은 값.
+ * 승인 토큰의 snapshotHash 바인딩과 비교되므로 결정적이어야 한다.
+ */
+export declare function computePreviewHash(input: {
+    projectId: string;
+    projectVersion: string;
+    mappingVersion: string;
+    members: TargetMember[];
+}): string;
+/**
+ * 재구매 조건 프로젝트의 대상을 산출한다.
+ * 읽기 전용 SELECT만 수행 — 운영 원천 테이블에는 어떤 쓰기도 하지 않는다.
+ */
+export declare function computeTargets(db: SqlExecutor, mapping: MappingConfig, project: ProjectDefinition, options?: {
+    now?: () => number;
+}): Promise<TargetComputation>;

package/dist/targets.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computePreviewHash = computePreviewHash;
+exports.computeTargets = computeTargets;
+const node_crypto_1 = require("node:crypto");
+const contracts_1 = require("./contracts");
+function ident(name) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]{0,62}$/.test(name)) {
+        throw new Error(`잘못된 식별자: ${name}`);
+    }
+    return `"${name}"`;
+}
+function tableRef(t) {
+    return `${ident(t.schema)}.${ident(t.table)}`;
+}
+/**
+ * 스냅샷/미리보기 해시 — 같은 대상 집합이면 항상 같은 값.
+ * 승인 토큰의 snapshotHash 바인딩과 비교되므로 결정적이어야 한다.
+ */
+function computePreviewHash(input) {
+    const keys = input.members.map((m) => m.customerKey).sort();
+    const canonical = JSON.stringify({
+        projectId: input.projectId,
+        projectVersion: input.projectVersion,
+        mappingVersion: input.mappingVersion,
+        customerKeys: keys,
+    });
+    return (0, node_crypto_1.createHash)("sha256").update(canonical).digest("hex");
+}
+/**
+ * 재구매 조건 프로젝트의 대상을 산출한다.
+ * 읽기 전용 SELECT만 수행 — 운영 원천 테이블에는 어떤 쓰기도 하지 않는다.
+ */
+async function computeTargets(db, mapping, project, options) {
+    const now = options?.now ?? Date.now;
+    const c = mapping.customer;
+    const r = mapping.reservation;
+    const col = (entity, field) => {
+        const column = entity.fields[field];
+        if (!column)
+            throw new Error(`매핑되지 않은 필드: ${field}`);
+        return ident(column);
+    };
+    const channelCol = c.fields.kakaoChannelStatus
+        ? `cust.${col(c, "kakaoChannelStatus")}`
+        : "NULL";
+    const cond = project.conditions;
+    const nowMs = now();
+    const windowEnd = new Date(nowMs - cond.daysSincePickupMin * 86_400_000);
+    const windowStart = new Date(nowMs - cond.daysSincePickupMax * 86_400_000);
+    const params = [windowStart.toISOString(), windowEnd.toISOString()];
+    let productFilter = "";
+    if (cond.productIds?.length) {
+        params.push(cond.productIds);
+        productFilter = `AND res.${col(r, "productId")}::text = ANY($${params.length})`;
+    }
+    // 윈도우 내 픽업완료가 있는 고객만 — 동의/채널 판정은 fail-closed로 TS에서 수행
+    const rows = (await db.selectRows(`SELECT DISTINCT
+       cust.${col(c, "customerKey")}::text   AS customer_key,
+       cust.${col(c, "phoneNumberHash")}     AS phone_hash,
+       cust.${col(c, "marketingOptIn")}      AS marketing_opt_in,
+       ${channelCol}                          AS kakao_channel_status
+     FROM ${tableRef(c.table)} cust
+     JOIN ${tableRef(r.table)} res
+       ON res.${col(r, "customerKey")}::text = cust.${col(c, "customerKey")}::text
+     WHERE res.${col(r, "pickupCompletedAt")} >= $1
+       AND res.${col(r, "pickupCompletedAt")} < $2
+       ${productFilter}`, params));
+    const exclusionCounts = new Map();
+    const exclude = (reason) => exclusionCounts.set(reason, (exclusionCounts.get(reason) ?? 0) + 1);
+    const seenPhoneHashes = new Set();
+    const members = [];
+    for (const row of rows) {
+        const phoneHash = row.phone_hash == null ? null : String(row.phone_hash);
+        if (!phoneHash) {
+            exclude(contracts_1.EXCLUSION_REASON.PHONE_MISSING);
+            continue;
+        }
+        const optIn = row.marketing_opt_in;
+        if (optIn === false) {
+            exclude(contracts_1.EXCLUSION_REASON.MARKETING_OPT_OUT);
+            continue;
+        }
+        // 브랜드 메시지(광고성)는 동의·채널 상태가 명확해야 한다 — 불명확이면 무조건 제외
+        if (project.channel === "brand") {
+            const channel = row.kakao_channel_status == null ? null : String(row.kakao_channel_status);
+            if (optIn !== true || channel === null || channel === "needs_check") {
+                exclude(contracts_1.EXCLUSION_REASON.CONSENT_AMBIGUOUS);
+                continue;
+            }
+            if (channel === "blocked") {
+                exclude(contracts_1.EXCLUSION_REASON.CHANNEL_BLOCKED);
+                continue;
+            }
+            if (channel === "unsubscribed") {
+                exclude(contracts_1.EXCLUSION_REASON.UNSUBSCRIBED);
+                continue;
+            }
+        }
+        if (seenPhoneHashes.has(phoneHash)) {
+            exclude(contracts_1.EXCLUSION_REASON.DUPLICATE);
+            continue;
+        }
+        seenPhoneHashes.add(phoneHash);
+        members.push({ customerKey: String(row.customer_key), phoneHash });
+    }
+    const previewHash = computePreviewHash({
+        projectId: project.projectId,
+        projectVersion: project.projectVersion,
+        mappingVersion: mapping.version,
+        members,
+    });
+    return {
+        members,
+        exclusions: [...exclusionCounts.entries()].map(([reason, count]) => ({
+            reason,
+            count,
+        })),
+        previewHash,
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,20 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ConnectorConfig, MappingConfig } from "./config";
+import type { DbAdapter } from "./db/adapter";
+import type { PlatformClient } from "./platform";
+/**
+ * MCP 도구 본 구현 (MVP 9종).
+ * 승인 경계: 쓰기/발송 도구는 플랫폼의 /api/approvals/consume으로 토큰을
+ * 검증·소비한 뒤에만 실행된다. 검증 실패 코드는 ERROR_HINTS와 함께 반환되어
+ * AI 운전 계층이 다음 행동을 결정할 수 있다 (AGENTS.md 계약).
+ */
+export interface ToolRuntime {
+    config: ConnectorConfig;
+    platform: PlatformClient;
+    /** 최초 사용 시 connect()까지 끝난 어댑터를 반환해야 한다 */
+    getDb: () => Promise<DbAdapter>;
+    /** validate_mapping(persist=true) 통과본을 설정에 반영 */
+    persistMapping: (mapping: MappingConfig) => Promise<void>;
+    now?: () => number;
+}
+export declare function registerTools(server: McpServer, rt: ToolRuntime): void;