@crmforall/connector 0.1.0

package/dist/db/crm-schema.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSchemaName = validateSchemaName;
+exports.migrateCrmSchema = migrateCrmSchema;
+/**
+ * CRM 전용 스키마 DDL — 멱등 (CREATE TABLE IF NOT EXISTS).
+ * 근거: 01_데이터_모델 §고객사 측 CRM 스키마 (기존 9테이블 중 MVP 사용분).
+ * 구조는 고객사 DB든 관리형 테넌트 스키마든 동일해야 한다 (내보내기 보장의 기반).
+ * 호출 시점: 설치 단계(connect init)에만 — DDL 권한은 설치 시에만 허용된다.
+ */
+function validateSchemaName(crmSchema) {
+    if (!/^[a-z_][a-z0-9_]{0,62}$/.test(crmSchema)) {
+        throw new Error(`잘못된 스키마 이름: ${crmSchema}`);
+    }
+}
+async function migrateCrmSchema(db, crmSchema) {
+    validateSchemaName(crmSchema);
+    const s = crmSchema;
+    const ddl = [
+        `CREATE SCHEMA IF NOT EXISTS ${s}`,
+        `CREATE TABLE IF NOT EXISTS ${s}.crm_field_mappings (
+      version       TEXT PRIMARY KEY,
+      mapping       JSONB NOT NULL,
+      created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+    )`,
+        `CREATE TABLE IF NOT EXISTS ${s}.crm_target_snapshots (
+      snapshot_id     TEXT PRIMARY KEY,
+      project_id      TEXT NOT NULL,
+      project_version TEXT NOT NULL,
+      mapping_version TEXT NOT NULL,
+      snapshot_hash   TEXT NOT NULL,
+      approval_id     TEXT NOT NULL UNIQUE,
+      target_count    INT NOT NULL,
+      exclusions      JSONB NOT NULL,
+      created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
+    )`,
+        `CREATE TABLE IF NOT EXISTS ${s}.crm_snapshot_members (
+      snapshot_id   TEXT NOT NULL REFERENCES ${s}.crm_target_snapshots(snapshot_id),
+      customer_key  TEXT NOT NULL,
+      phone_hash    TEXT NOT NULL,
+      PRIMARY KEY (snapshot_id, customer_key)
+    )`,
+        `CREATE TABLE IF NOT EXISTS ${s}.crm_events (
+      event_id      TEXT PRIMARY KEY,
+      event_type    TEXT NOT NULL,
+      payload       JSONB NOT NULL,
+      approval_id   TEXT NOT NULL,
+      created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+    )`,
+        `CREATE TABLE IF NOT EXISTS ${s}.crm_send_jobs (
+      send_job_id     TEXT PRIMARY KEY,
+      snapshot_id     TEXT NOT NULL REFERENCES ${s}.crm_target_snapshots(snapshot_id),
+      channel         TEXT NOT NULL,
+      message_version TEXT NOT NULL,
+      approval_id     TEXT NOT NULL UNIQUE,
+      status          TEXT NOT NULL DEFAULT 'queued',
+      created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
+    )`,
+        `CREATE TABLE IF NOT EXISTS ${s}.crm_send_results (
+      send_job_id   TEXT NOT NULL REFERENCES ${s}.crm_send_jobs(send_job_id),
+      receiver_ref  TEXT NOT NULL,
+      status        TEXT NOT NULL,
+      provider_code TEXT,
+      internal_code TEXT,
+      synced_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
+      PRIMARY KEY (send_job_id, receiver_ref)
+    )`,
+        `CREATE TABLE IF NOT EXISTS ${s}.crm_engagements (
+      event_id        TEXT PRIMARY KEY,
+      identity_key    TEXT NOT NULL,
+      engagement_type TEXT NOT NULL,
+      campaign_ref    TEXT,
+      short_link_ref  TEXT,
+      reservation_ref TEXT,
+      pickup_amount   NUMERIC,
+      occurred_at     TIMESTAMPTZ NOT NULL,
+      created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
+    )`,
+        `CREATE TABLE IF NOT EXISTS ${s}.crm_audit_logs (
+      id            BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+      actor         TEXT NOT NULL,
+      action        TEXT NOT NULL,
+      detail        JSONB,
+      created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+    )`,
+    ];
+    for (const sql of ddl) {
+        await db.execute(sql);
+    }
+}

package/dist/db/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./adapter";
+export * from "./postgres";
+export * from "./crm-schema";

package/dist/db/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./adapter"), exports);
+__exportStar(require("./postgres"), exports);
+__exportStar(require("./crm-schema"), exports);

package/dist/db/postgres.d.ts

@@ -0,0 +1,31 @@
+import type { ColumnInfo, DbAdapter, ReadinessReport } from "./adapter";
+export interface PostgresCredentials {
+    host: string;
+    port: number;
+    database: string;
+    user: string;
+    password: string;
+    ssl?: boolean;
+}
+export declare class PostgresAdapter implements DbAdapter {
+    private readonly creds;
+    readonly sourceType: "postgresql";
+    private client;
+    constructor(creds: PostgresCredentials);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    private q;
+    selectRows(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+    execute(sql: string, params?: unknown[]): Promise<{
+        rowCount: number;
+    }>;
+    checkReadiness({ crmSchema }: {
+        crmSchema: string;
+    }): Promise<ReadinessReport>;
+    listColumns({ schemaAllowlist }: {
+        schemaAllowlist?: string[];
+    }): Promise<ColumnInfo[]>;
+    ensureCrmSchema({ crmSchema }: {
+        crmSchema: string;
+    }): Promise<void>;
+}

package/dist/db/postgres.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresAdapter = void 0;
+const pg_1 = require("pg");
+const crm_schema_1 = require("./crm-schema");
+/** 시스템 스키마 — 탐색·검사 대상에서 제외 */
+const SYSTEM_SCHEMAS = ["pg_catalog", "information_schema", "pg_toast"];
+class PostgresAdapter {
+    creds;
+    sourceType = "postgresql";
+    client = null;
+    constructor(creds) {
+        this.creds = creds;
+    }
+    async connect() {
+        const client = new pg_1.Client({
+            host: this.creds.host,
+            port: this.creds.port,
+            database: this.creds.database,
+            user: this.creds.user,
+            password: this.creds.password,
+            ssl: this.creds.ssl ? { rejectUnauthorized: false } : undefined,
+            connectionTimeoutMillis: 10_000,
+        });
+        await client.connect();
+        this.client = client;
+    }
+    async disconnect() {
+        await this.client?.end();
+        this.client = null;
+    }
+    q() {
+        if (!this.client)
+            throw new Error("connect()를 먼저 호출하세요");
+        return this.client;
+    }
+    async selectRows(sql, params = []) {
+        const res = await this.q().query(sql, params);
+        return res.rows;
+    }
+    async execute(sql, params = []) {
+        const res = await this.q().query(sql, params);
+        return { rowCount: res.rowCount ?? 0 };
+    }
+    async checkReadiness({ crmSchema }) {
+        const checks = [];
+        const client = this.q();
+        checks.push({ name: "connect", passed: true, detail: "DB 연결 성공" });
+        // 1. 운영 스키마 SELECT 가능 여부
+        const selectable = await client.query(`SELECT count(*)::int AS n FROM information_schema.table_privileges
+       WHERE grantee = current_user AND privilege_type = 'SELECT'
+         AND table_schema NOT IN (${SYSTEM_SCHEMAS.map((_, i) => `$${i + 1}`).join(",")})
+         AND table_schema <> $${SYSTEM_SCHEMAS.length + 1}`, [...SYSTEM_SCHEMAS, crmSchema]);
+        const selectCount = selectable.rows[0].n;
+        checks.push({
+            name: "operational_select",
+            passed: selectCount > 0,
+            detail: selectCount > 0
+                ? `운영 테이블 ${selectCount}개에 SELECT 권한 확인`
+                : "운영 테이블 SELECT 권한이 없습니다. 읽기 전용 권한을 요청하세요.",
+        });
+        // 2. 운영 원천 테이블 쓰기 권한 — 있으면 과권한 (활성화 차단)
+        const writable = await client.query(`SELECT DISTINCT table_schema, table_name FROM information_schema.table_privileges
+       WHERE grantee = current_user
+         AND privilege_type IN ('INSERT','UPDATE','DELETE')
+         AND table_schema NOT IN (${SYSTEM_SCHEMAS.map((_, i) => `$${i + 1}`).join(",")})
+         AND table_schema <> $${SYSTEM_SCHEMAS.length + 1}
+       LIMIT 20`, [...SYSTEM_SCHEMAS, crmSchema]);
+        const overprivileged = writable.rows.length > 0;
+        checks.push({
+            name: "source_table_write_blocked",
+            passed: !overprivileged,
+            detail: overprivileged
+                ? `운영 원천 테이블 ${writable.rows.length}개에 쓰기 권한이 감지되었습니다 (과권한). 활성화가 차단됩니다.`
+                : "운영 원천 테이블 쓰기 권한 없음 (정상)",
+            remediationSql: overprivileged
+                ? writable.rows
+                    .map((r) => `REVOKE INSERT, UPDATE, DELETE ON ${r.table_schema}.${r.table_name} FROM ${this.creds.user};`)
+                    .join("\n")
+                : undefined,
+        });
+        // 3. CRM 전용 스키마 존재 여부
+        const schemaExists = await client.query(`SELECT 1 FROM information_schema.schemata WHERE schema_name = $1`, [crmSchema]);
+        const crmExists = (schemaExists.rowCount ?? 0) > 0;
+        checks.push({
+            name: "crm_schema_exists",
+            passed: crmExists,
+            detail: crmExists
+                ? `CRM 전용 스키마 ${crmSchema} 존재`
+                : `CRM 전용 스키마 ${crmSchema}가 없습니다. connect init이 생성합니다.`,
+        });
+        // 4. CRM 스키마 쓰기 가능 여부
+        let crmWritable = false;
+        if (crmExists) {
+            const crmWrite = await client.query(`SELECT count(*)::int AS n FROM information_schema.table_privileges
+         WHERE grantee = current_user AND table_schema = $1
+           AND privilege_type IN ('INSERT','UPDATE')`, [crmSchema]);
+            const usage = await client.query(`SELECT has_schema_privilege(current_user, $1, 'CREATE') AS c`, [crmSchema]);
+            crmWritable = crmWrite.rows[0].n > 0 || usage.rows[0].c === true;
+        }
+        checks.push({
+            name: "crm_schema_write",
+            passed: crmWritable,
+            detail: crmWritable
+                ? "CRM 스키마 쓰기 권한 확인"
+                : "CRM 스키마 쓰기 권한이 없습니다.",
+        });
+        const ready = !overprivileged &&
+            checks
+                .filter((c) => c.name !== "ddl_limited")
+                .every((c) => c.passed);
+        return { ready, overprivileged, checks };
+    }
+    async listColumns({ schemaAllowlist }) {
+        const client = this.q();
+        const params = [...SYSTEM_SCHEMAS];
+        let where = `table_schema NOT IN (${SYSTEM_SCHEMAS.map((_, i) => `$${i + 1}`).join(",")})`;
+        if (schemaAllowlist?.length) {
+            where += ` AND table_schema = ANY($${params.length + 1})`;
+            params.push(schemaAllowlist);
+        }
+        const res = await client.query(`SELECT table_schema, table_name, column_name, data_type
+       FROM information_schema.columns WHERE ${where}
+       ORDER BY table_schema, table_name, ordinal_position`, schemaAllowlist?.length ? [...SYSTEM_SCHEMAS, schemaAllowlist] : [...SYSTEM_SCHEMAS]);
+        return res.rows.map((r) => ({
+            schema: r.table_schema,
+            table: r.table_name,
+            column: r.column_name,
+            dataType: r.data_type,
+        }));
+    }
+    async ensureCrmSchema({ crmSchema }) {
+        this.q();
+        // 멱등: IF NOT EXISTS. 식별자는 파라미터 바인딩이 불가하므로 엄격 검증 후 사용.
+        await (0, crm_schema_1.migrateCrmSchema)(this, crmSchema);
+    }
+}
+exports.PostgresAdapter = PostgresAdapter;

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { ConnectorConfig } from "./config";
+import type { DbAdapter } from "./db/adapter";
+export * from "./config";
+export * from "./contracts";
+export * from "./mapping";
+export * from "./platform";
+export * from "./targets";
+export * from "./tools";
+/**
+ * crmforall MCP 커넥터 라이브러리 진입점.
+ * 서버 기동은 server.ts(bin)에서 — CLI가 이 모듈을 import해도 서버가 뜨지 않는다.
+ */
+export declare function buildAdapter(config: ConnectorConfig): DbAdapter;

package/dist/index.js

@@ -0,0 +1,41 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAdapter = buildAdapter;
+const postgres_1 = require("./db/postgres");
+__exportStar(require("./config"), exports);
+__exportStar(require("./contracts"), exports);
+__exportStar(require("./mapping"), exports);
+__exportStar(require("./platform"), exports);
+__exportStar(require("./targets"), exports);
+__exportStar(require("./tools"), exports);
+/**
+ * crmforall MCP 커넥터 라이브러리 진입점.
+ * 서버 기동은 server.ts(bin)에서 — CLI가 이 모듈을 import해도 서버가 뜨지 않는다.
+ */
+function buildAdapter(config) {
+    if (config.db.sourceType !== "postgresql") {
+        throw new Error(`${config.db.sourceType} 어댑터는 아직 구현되지 않았습니다 (MVP: postgresql)`);
+    }
+    return new postgres_1.PostgresAdapter({
+        host: config.db.host,
+        port: config.db.port,
+        database: config.db.database,
+        user: config.db.user,
+        password: config.db.password,
+        ssl: config.db.ssl,
+    });
+}

package/dist/mapping.d.ts

@@ -0,0 +1,37 @@
+import type { ColumnInfo } from "./db/adapter";
+import type { MappingConfig } from "./config";
+/**
+ * 표준 필드 매핑 — 제안(휴리스틱)과 검증.
+ * 근거: 기존 SPEC §표준 데이터 모델, 수용 기준 "필수 표준 필드 전부 매핑돼야 활성화".
+ */
+type Entity = "customer" | "reservation";
+export interface MappingCandidate {
+    entity: Entity;
+    field: string;
+    required: boolean;
+    schema: string | null;
+    table: string | null;
+    column: string | null;
+    confidence: "high" | "medium" | "none";
+}
+export interface MappingProposal {
+    candidates: MappingCandidate[];
+    /** 엔터티별 가장 유력한 테이블 */
+    tables: Record<Entity, {
+        schema: string;
+        table: string;
+    } | null>;
+}
+/**
+ * 컬럼명 휴리스틱으로 표준 필드 매핑을 제안한다.
+ * 제안은 후보일 뿐 — 운영자가 검토·확정한 매핑만 validate_mapping을 거쳐 저장된다.
+ */
+export declare function proposeMapping(columns: ColumnInfo[]): MappingProposal;
+export interface MappingValidation {
+    valid: boolean;
+    missingRequired: string[];
+    /** 매핑이 가리키는 컬럼이 실제 스키마에 없는 항목 */
+    unknownColumns: string[];
+}
+export declare function validateMapping(mapping: MappingConfig, columns: ColumnInfo[]): MappingValidation;
+export {};

package/dist/mapping.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.proposeMapping = proposeMapping;
+exports.validateMapping = validateMapping;
+const contracts_1 = require("./contracts");
+const HEURISTICS = [
+    { field: "customerKey", entity: "customer", required: true,
+        synonyms: ["customer_key", "customer_id", "member_id", "member_no", "user_id", "id"] },
+    { field: "name", entity: "customer", required: false,
+        synonyms: ["name", "customer_name", "member_name", "user_name"] },
+    { field: "phoneNumberHash", entity: "customer", required: true,
+        synonyms: ["phone_number_hash", "phone_hash", "phone_sha256", "hp_hash"] },
+    { field: "marketingOptIn", entity: "customer", required: true,
+        synonyms: ["marketing_opt_in", "marketing_agree", "ad_agree", "sms_agree", "marketing_consent"] },
+    { field: "kakaoChannelStatus", entity: "customer", required: false,
+        synonyms: ["kakao_channel_status", "kakao_status", "channel_status", "friend_status"] },
+    { field: "updatedAt", entity: "customer", required: false,
+        synonyms: ["updated_at", "modified_at", "mod_date", "upd_dt"] },
+    { field: "reservationId", entity: "reservation", required: true,
+        synonyms: ["reservation_id", "reserve_id", "booking_id", "order_id", "id"] },
+    { field: "customerKey", entity: "reservation", required: true,
+        synonyms: ["customer_key", "customer_id", "member_id", "member_no", "user_id"] },
+    { field: "productId", entity: "reservation", required: true,
+        synonyms: ["product_id", "item_id", "goods_id", "sku"] },
+    { field: "reservedAt", entity: "reservation", required: false,
+        synonyms: ["reserved_at", "reservation_date", "booked_at", "created_at"] },
+    { field: "reservationStatus", entity: "reservation", required: false,
+        synonyms: ["reservation_status", "status", "state"] },
+    { field: "pickupCompletedAt", entity: "reservation", required: true,
+        synonyms: ["pickup_completed_at", "pickup_at", "picked_up_at", "pickup_done_at", "completed_at"] },
+    { field: "pickupAmount", entity: "reservation", required: false,
+        synonyms: ["pickup_amount", "amount", "total_amount", "price", "pay_amount"] },
+    { field: "pharmacyId", entity: "reservation", required: false,
+        synonyms: ["pharmacy_id", "store_id", "branch_id", "shop_id"] },
+];
+const CUSTOMER_TABLE_HINTS = ["member", "customer", "user"];
+const RESERVATION_TABLE_HINTS = ["reservation", "reserve", "booking", "order", "pickup"];
+function pickTable(columns, hints) {
+    const byTable = new Map();
+    for (const c of columns) {
+        const key = `${c.schema}.${c.table}`;
+        byTable.set(key, [...(byTable.get(key) ?? []), c]);
+    }
+    let best = null;
+    for (const [, cols] of byTable) {
+        const { schema, table } = cols[0];
+        const nameScore = hints.some((h) => table.toLowerCase().includes(h)) ? 10 : 0;
+        if (nameScore === 0)
+            continue;
+        const score = nameScore + cols.length / 100;
+        if (!best || score > best.score)
+            best = { schema, table, score };
+    }
+    return best ? { schema: best.schema, table: best.table } : null;
+}
+/**
+ * 컬럼명 휴리스틱으로 표준 필드 매핑을 제안한다.
+ * 제안은 후보일 뿐 — 운영자가 검토·확정한 매핑만 validate_mapping을 거쳐 저장된다.
+ */
+function proposeMapping(columns) {
+    const tables = {
+        customer: pickTable(columns, CUSTOMER_TABLE_HINTS),
+        reservation: pickTable(columns, RESERVATION_TABLE_HINTS),
+    };
+    const candidates = HEURISTICS.map((h) => {
+        const target = tables[h.entity];
+        const pool = target
+            ? columns.filter((c) => c.schema === target.schema && c.table === target.table)
+            : columns;
+        for (const [rank, syn] of h.synonyms.entries()) {
+            const hit = pool.find((c) => c.column.toLowerCase() === syn);
+            if (hit) {
+                return {
+                    entity: h.entity,
+                    field: h.field,
+                    required: h.required,
+                    schema: hit.schema,
+                    table: hit.table,
+                    column: hit.column,
+                    // 첫 후보 정확 일치는 high, 뒤로 갈수록(일반어 id 등) medium
+                    confidence: rank === 0 ? "high" : "medium",
+                };
+            }
+        }
+        return {
+            entity: h.entity,
+            field: h.field,
+            required: h.required,
+            schema: null,
+            table: null,
+            column: null,
+            confidence: "none",
+        };
+    });
+    return { candidates, tables };
+}
+/** 필수 표준 필드 → 소속 엔터티 */
+const REQUIRED_FIELD_ENTITY = {
+    customerKey: "customer",
+    phoneNumberHash: "customer",
+    marketingOptIn: "customer",
+    reservationId: "reservation",
+    productId: "reservation",
+    pickupCompletedAt: "reservation",
+};
+function validateMapping(mapping, columns) {
+    const missingRequired = [];
+    for (const field of contracts_1.REQUIRED_MAPPING_FIELDS) {
+        const entity = REQUIRED_FIELD_ENTITY[field];
+        if (!mapping[entity].fields[field])
+            missingRequired.push(field);
+    }
+    // 예약→고객 조인 키는 별도 필수
+    if (!mapping.reservation.fields.customerKey) {
+        missingRequired.push("reservation.customerKey");
+    }
+    const unknownColumns = [];
+    for (const entity of ["customer", "reservation"]) {
+        const { table, fields } = mapping[entity];
+        for (const [field, column] of Object.entries(fields)) {
+            const exists = columns.some((c) => c.schema === table.schema &&
+                c.table === table.table &&
+                c.column === column);
+            if (!exists) {
+                unknownColumns.push(`${entity}.${field} → ${table.schema}.${table.table}.${column}`);
+            }
+        }
+    }
+    return {
+        valid: missingRequired.length === 0 && unknownColumns.length === 0,
+        missingRequired,
+        unknownColumns,
+    };
+}

package/dist/platform.d.ts

@@ -0,0 +1,114 @@
+import { type ApprovalScope, type ErrorCode } from "./contracts";
+/**
+ * CRM API(플랫폼) 클라이언트.
+ * 승인 토큰의 시크릿·단회용 nonce 저장소는 플랫폼에만 있다 — 커넥터는
+ * 검증·소비를 플랫폼에 위임하고 결과 claims만 받는다 (03_CRM_API §인증 모델).
+ * 커넥터 인증: X-Connector-Id + Bearer connectorSecret (아웃바운드 전용).
+ */
+export interface ApprovalClaims {
+    scope: ApprovalScope;
+    tenantId: string;
+    approvalId: string;
+    approverId: string;
+    snapshotHash: string | null;
+    projectVersion: string | null;
+    messageVersion: string | null;
+}
+export type ConsumeResult = {
+    ok: true;
+    claims: ApprovalClaims;
+} | {
+    ok: false;
+    code: ErrorCode;
+    message: string;
+};
+export interface ProjectDefinition {
+    projectId: string;
+    projectVersion: string;
+    channel: "alimtalk" | "brand";
+    conditions: {
+        type: "repurchase";
+        /** 픽업완료 후 경과일 범위 (재구매 유도 윈도우) */
+        daysSincePickupMin: number;
+        daysSincePickupMax: number;
+        /** 상품 제한 (null = 전체) */
+        productIds: string[] | null;
+    };
+}
+export interface SendJobStatus {
+    sendJobId: string;
+    status: "queued" | "sending" | "done" | "failed";
+    results: Array<{
+        receiverRef: string;
+        status: "success" | "failed" | "retryable";
+        providerCode: string | null;
+        internalCode: string | null;
+    }>;
+}
+export interface EngagementReport {
+    identityKey: string;
+    engagementType: "click" | "reservation" | "pickup_completed";
+    campaignRef: string | null;
+    shortLinkRef: string | null;
+    reservationRef: string | null;
+    pickupAmount: number | null;
+    occurredAt: string;
+}
+export interface PlatformClient {
+    consumeApproval(input: {
+        token: string;
+        expectedScope: ApprovalScope;
+        snapshotHash?: string | null;
+    }): Promise<ConsumeResult>;
+    getProjectDefinition(projectId: string): Promise<ProjectDefinition>;
+    /** 반응 기록 중계 — 깔때기 리포트 집계용 (로컬 crm_engagements가 원본) */
+    reportEngagement(input: EngagementReport): Promise<void>;
+    createSendJob(input: {
+        approvalId: string;
+        snapshotId: string;
+        snapshotHash: string;
+        messageVersion: string;
+        channel: "alimtalk" | "brand";
+        targetCount: number;
+        /** 깔때기 리포트 귀속 기준 (스냅샷의 project_id) */
+        campaignRef: string | null;
+    }): Promise<{
+        sendJobId: string;
+    }>;
+    getSendJob(sendJobId: string): Promise<SendJobStatus>;
+}
+export interface HttpPlatformClientOptions {
+    platformUrl: string;
+    connectorId: string;
+    connectorSecret: string;
+    fetchImpl?: typeof fetch;
+}
+export declare class PlatformError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+}
+export declare class HttpPlatformClient implements PlatformClient {
+    private readonly opts;
+    private readonly fetchImpl;
+    constructor(opts: HttpPlatformClientOptions);
+    private request;
+    consumeApproval(input: {
+        token: string;
+        expectedScope: ApprovalScope;
+        snapshotHash?: string | null;
+    }): Promise<ConsumeResult>;
+    getProjectDefinition(projectId: string): Promise<ProjectDefinition>;
+    reportEngagement(input: EngagementReport): Promise<void>;
+    createSendJob(input: {
+        approvalId: string;
+        snapshotId: string;
+        snapshotHash: string;
+        messageVersion: string;
+        channel: "alimtalk" | "brand";
+        targetCount: number;
+        campaignRef: string | null;
+    }): Promise<{
+        sendJobId: string;
+    }>;
+    getSendJob(sendJobId: string): Promise<SendJobStatus>;
+}