adyou 0.3.0

package/dist/adapters/meta.js

@@ -0,0 +1,275 @@
+// Meta(Facebook·Instagram) — Marketing API(Graph v23) 직접 호출. 시스템 사용자 토큰. 오늘(2026-09-14) 실측 함정 반영:
+//   예산=계정 통화 최소 단위 · Advantage+ 오디언스에선 age_max 금지 · DCO 광고세트엔 광고 1개(컨셉=광고세트) · instagram_user_id · WITH_ISSUES 2446984는 조치 불필요
+//   앱 개발 모드면 크리에이티브 생성 100 오류 · 픽셀 트래픽 권한 밖 도메인은 이벤트 조용히 폐기(signals/config blockReason)
+import fs from 'node:fs';
+import { MediumError, nameTag, utm } from './types.js';
+const G = 'https://graph.facebook.com/v23.0';
+const REQUIRED_SCOPES = ['ads_management', 'ads_read', 'business_management', 'pages_show_list', 'pages_read_engagement', 'pages_manage_ads'];
+const COUNTRY_INTERESTS = {};
+void COUNTRY_INTERESTS;
+export class MetaConnector {
+    c;
+    medium = 'meta';
+    constructor(c) {
+        this.c = c;
+    }
+    async call(method, path, params = {}) {
+        const body = new URLSearchParams();
+        for (const [k, v] of Object.entries(params))
+            if (v !== undefined && v !== null)
+                body.set(k, typeof v === 'string' ? v : JSON.stringify(v));
+        body.set('access_token', this.c.accessToken);
+        const url = method === 'GET' ? `${G}/${path}?${body}` : `${G}/${path}`;
+        const res = await fetch(url, { method, body: method === 'GET' ? undefined : body, signal: AbortSignal.timeout(120_000) });
+        const data = (await res.json().catch(() => ({})));
+        if (!res.ok || data.error)
+            throw this.wrap(data.error, path);
+        return data;
+    }
+    wrap(e, path) {
+        const msg = e?.error_user_msg || e?.message || '알 수 없는 오류';
+        let hint;
+        if (e?.code === 190)
+            hint = '토큰이 만료·무효예요. Business Suite › 설정 › 사용자 › 시스템 사용자 › 토큰 생성 을 다시 하고 `adpilot connect meta` 로 넣어 주세요.';
+        else if (/개발 모드|development mode|public mode/i.test(msg))
+            hint = '앱이 개발 모드예요. developers.facebook.com › 앱 › 상단 「앱 모드」를 라이브로 바꿔 주세요(심사 불필요).';
+        else if (e?.code === 200 || e?.code === 10 || /permission/i.test(msg))
+            hint = '권한이 부족해요. 시스템 사용자에게 광고 계정·페이지·픽셀 자산이 할당됐는지, 토큰 스코프에 ads_management·pages_manage_ads가 있는지 확인해 주세요.';
+        else if (/dynamic creative|다이내믹 크리에이티브/i.test(msg))
+            hint = 'DCO 광고세트엔 광고 1개만 들어가요. adpilot은 컨셉마다 광고세트를 따로 만드는데, 손으로 추가한 광고가 있는지 확인해 주세요.';
+        else if (/age_max|최대 연령/i.test(msg))
+            hint = 'Advantage+ 오디언스에선 최대 연령을 강제할 수 없어요 — 타겟에서 age_max를 빼 주세요.';
+        else if (/budget|예산/i.test(msg))
+            hint = '예산은 계정 통화의 최소 단위(USD는 센트)예요. 광고세트당 하루 최소 약 $1·₩1,500 이상이어야 해요.';
+        return new MediumError('meta', `Meta ${path}: ${msg}${e?.code ? ` (code ${e.code}${e.error_subcode ? `/${e.error_subcode}` : ''})` : ''}`, hint, e);
+    }
+    async account() {
+        const a = await this.call('GET', this.c.adAccountId, { fields: 'id,name,currency,account_status,timezone_name,spend_cap,amount_spent,funding_source_details' });
+        return { id: a.id, name: a.name, currency: a.currency, timezone: a.timezone_name, status: a.account_status === 1 ? 'ACTIVE' : String(a.account_status), extra: { spend_cap: a.spend_cap, amount_spent: a.amount_spent, funding: a.funding_source_details?.display_string } };
+    }
+    async check(landingUrl) {
+        const items = [];
+        // 1) 토큰
+        try {
+            const d = await this.call('GET', 'debug_token', { input_token: this.c.accessToken });
+            const t = d.data;
+            const missing = REQUIRED_SCOPES.filter((s) => !(t.scopes || []).includes(s));
+            items.push({ key: 'meta.token', ok: !!t.is_valid, title: '토큰 유효', detail: `${t.type || '?'} · 앱 ${t.application || t.app_id || '?'} · ${t.expires_at ? `만료 ${new Date(t.expires_at * 1000).toISOString().slice(0, 10)}` : '만료 없음'}`, fix: t.is_valid ? undefined : '시스템 사용자 토큰을 다시 생성해 주세요.' });
+            items.push({ key: 'meta.token.type', ok: t.type === 'SYSTEM_USER', title: '토큰 종류 = 시스템 사용자', detail: t.type || '?', fix: t.type === 'SYSTEM_USER' ? undefined : '개인 사용자 토큰은 60일 만료·권한 흔들림이 있어요. Business Suite › 설정 › 사용자 › 시스템 사용자 에서 만든 토큰을 쓰세요.' });
+            items.push({ key: 'meta.scopes', ok: !missing.length, title: '토큰 권한(스코프)', detail: missing.length ? `빠진 권한: ${missing.join(', ')}` : (t.scopes || []).join(', '), fix: missing.length ? '시스템 사용자 › 토큰 생성 에서 빠진 권한을 체크해 새 토큰을 만들어 주세요(read_insights는 UI에 없음 → ads_read로 충분).' : undefined });
+            if (t.app_id)
+                this.c.appId = this.c.appId || t.app_id;
+        }
+        catch (e) {
+            items.push({ key: 'meta.token', ok: false, title: '토큰 유효', detail: e instanceof Error ? e.message : String(e), fix: e.hint });
+        }
+        // 2) 광고 계정
+        try {
+            const a = await this.account();
+            items.push({ key: 'meta.account', ok: a.status === 'ACTIVE', title: '광고 계정 상태', detail: `${a.name} (${a.id}) · ${a.status}`, fix: a.status === 'ACTIVE' ? undefined : '광고 계정이 비활성·정지 상태예요. 광고 관리자 › 계정 품질 에서 확인해 주세요.' });
+            items.push({ key: 'meta.currency', ok: true, title: '계정 통화(예산 최소 단위)', detail: `${a.currency} — 예산은 ${a.currency === 'KRW' ? '원 단위 정수' : `${a.currency} 최소 단위(센트)로 환산`}해서 보냅니다` });
+            items.push({ key: 'meta.funding', ok: a.extra?.funding ? true : null, title: '결제 수단', detail: String(a.extra?.funding || '조회 권한 없음 — 광고 관리자 › 결제 설정 에서 확인'), fix: a.extra?.funding ? undefined : '결제 수단이 없으면 광고가 시작되지 않아요. business.facebook.com › 결제 설정 에서 카드를 등록해 주세요.' });
+        }
+        catch (e) {
+            items.push({ key: 'meta.account', ok: false, title: '광고 계정 접근', detail: e instanceof Error ? e.message : String(e), fix: e.hint || '시스템 사용자에게 이 광고 계정을 자산으로 할당해 주세요.' });
+        }
+        // 3) 페이지·인스타
+        if (this.c.pageId) {
+            try {
+                const p = await this.call('GET', this.c.pageId, { fields: 'name,instagram_business_account' });
+                items.push({ key: 'meta.page', ok: true, title: '페이지(광고 신원)', detail: `${p.name} (${this.c.pageId})` });
+                const ig = this.c.instagramActorId || p.instagram_business_account?.id;
+                items.push({ key: 'meta.instagram', ok: ig ? true : null, title: '인스타그램 계정 연결', detail: ig ? `IG ${ig}` : '연결된 인스타그램 비즈니스 계정이 없어요(페이지 이름으로 인스타 노출)', fix: ig ? undefined : 'Business Suite › 설정 › 인스타그램 계정 에서 연결하면 인스타 광고가 브랜드 계정으로 나가요.' });
+                if (ig && !this.c.instagramActorId)
+                    this.c.instagramActorId = ig;
+            }
+            catch (e) {
+                items.push({ key: 'meta.page', ok: false, title: '페이지 접근', detail: e instanceof Error ? e.message : String(e), fix: '시스템 사용자에게 페이지 자산을 할당하고 pages_show_list·pages_manage_ads 스코프를 주세요.' });
+            }
+        }
+        else
+            items.push({ key: 'meta.page', ok: false, title: '페이지 id', detail: '설정되지 않음', fix: '`adpilot connect meta --page <페이지 id>` — 광고는 페이지 이름으로 나가요.' });
+        // 4) 픽셀
+        if (this.c.pixelId) {
+            try {
+                const px = await this.call('GET', this.c.pixelId, { fields: 'name,last_fired_time' });
+                const recent = px.last_fired_time ? Date.now() - new Date(px.last_fired_time).getTime() < 3 * 86400_000 : false;
+                items.push({ key: 'meta.pixel', ok: true, title: '픽셀 존재', detail: `${px.name} (${this.c.pixelId}) · 마지막 수신 ${px.last_fired_time || '없음'}` });
+                items.push({ key: 'meta.pixel.recent', ok: recent ? true : null, title: '픽셀 최근 3일 수신', detail: recent ? '수신 중' : '최근 이벤트 없음 — 랜딩에 픽셀이 심어졌는지 `adpilot track verify` 로 확인', fix: recent ? undefined : '`adpilot track install` 로 스니펫을 발급해 사이트 <head> 에 넣어 주세요.' });
+                if (landingUrl)
+                    items.push(await this.pixelTrafficPermission(landingUrl));
+            }
+            catch (e) {
+                items.push({ key: 'meta.pixel', ok: false, title: '픽셀 접근', detail: e instanceof Error ? e.message : String(e), fix: '시스템 사용자에게 픽셀(데이터세트) 자산을 할당해 주세요.' });
+            }
+        }
+        else
+            items.push({ key: 'meta.pixel', ok: null, title: '픽셀', detail: '설정되지 않음 — 트래픽 목표로만 집행되고 전환 최적화는 못 해요', fix: '이벤트 관리자에서 픽셀을 만들고 `adpilot connect meta --pixel <id>`' });
+        // 5) 앱 모드 — API로 직접 조회 불가. 크리에이티브 생성 시 오류로 판정됨을 안내.
+        items.push({ key: 'meta.appmode', ok: null, title: '앱 라이브 모드', detail: 'API로 조회할 수 없어요. 개발 모드면 소재 생성 때 「개발 모드 앱」 오류로 멈춰요(그때 정확히 안내).', fix: 'developers.facebook.com › 내 앱 › 상단 토글을 「라이브」로. 심사 불필요(자기 계정만 씀).', link: 'https://developers.facebook.com/apps/' });
+        return items;
+    }
+    /** 픽셀 트래픽 권한 — connect.facebook.net/signals/config/<pixel>?domain=<host> 에 blockReason:"traffic_permissions" 가 있으면 이벤트가 조용히 버려진다 */
+    async pixelTrafficPermission(landingUrl) {
+        const host = new URL(landingUrl).hostname;
+        try {
+            const txt = await (await fetch(`https://connect.facebook.net/signals/config/${this.c.pixelId}?v=2.9&r=stable&domain=${host}`, { signal: AbortSignal.timeout(15_000) })).text();
+            const blocked = /"blockReason"\s*:\s*"traffic_permissions"/.test(txt);
+            return { key: 'meta.pixel.traffic', ok: !blocked, title: `픽셀 트래픽 권한(${host})`, detail: blocked ? `허용 목록에 ${host} 가 없어 이벤트가 조용히 폐기돼요` : '허용됨', fix: blocked ? `이벤트 관리자 › 데이터 소스 › 픽셀 › 설정 › 트래픽 권한 › 허용 목록에 ${host} 추가(API 없음 · 사람 몫).` : undefined, link: `https://business.facebook.com/events_manager2/list/pixel/${this.c.pixelId}/settings` };
+        }
+        catch (e) {
+            return { key: 'meta.pixel.traffic', ok: null, title: '픽셀 트래픽 권한', detail: `확인 실패: ${e instanceof Error ? e.message : e}` };
+        }
+    }
+    /** 프로젝트 전용 픽셀 — 이름으로 재사용 · 없으면 생성(새 픽셀은 트래픽 권한 제한이 없어 어느 도메인 이벤트든 받는다) */
+    async ensurePixel(name) {
+        const d = await this.call('GET', `${this.c.adAccountId}/adspixels`, { fields: 'id,name', limit: 200 });
+        const found = d.data.find((x) => x.name === name);
+        if (found)
+            return found.id;
+        return (await this.call('POST', `${this.c.adAccountId}/adspixels`, { name })).id;
+    }
+    async inventory() {
+        const rows = [];
+        const camps = await this.call('GET', `${this.c.adAccountId}/campaigns`, { fields: 'id,name,status,effective_status,objective,daily_budget,insights.date_preset(last_30d){spend,impressions,clicks}', limit: 200 });
+        for (const c of camps.data) {
+            const i = c.insights?.data?.[0];
+            rows.push({ level: 'campaign', id: c.id, name: c.name, status: c.status, effectiveStatus: c.effective_status, objective: c.objective, dailyBudgetMinor: c.daily_budget ? Number(c.daily_budget) : undefined, spend30d: i ? Number(i.spend) : 0, impressions30d: i ? Number(i.impressions) : 0, clicks30d: i ? Number(i.clicks) : 0 });
+        }
+        const ads = await this.call('GET', `${this.c.adAccountId}/ads`, { fields: 'id,name,status,effective_status,campaign_id,issues_info', limit: 500 });
+        for (const a of ads.data)
+            rows.push({ level: 'ad', id: a.id, name: a.name, status: a.status, effectiveStatus: a.effective_status, parent: a.campaign_id, issues: (a.issues_info || []).map((x) => x.error_summary || x.error_message || '').filter(Boolean) });
+        return rows;
+    }
+    async findByName(edge, name, extra = {}) {
+        const d = await this.call('GET', `${this.c.adAccountId}/${edge}`, { fields: 'id,name,status', limit: 500, filtering: [{ field: 'name', operator: 'CONTAIN', value: name.slice(0, 60) }], ...extra });
+        return d.data.find((x) => x.name === name) || null;
+    }
+    async uploadImage(file) {
+        const d = await this.call('POST', `${this.c.adAccountId}/adimages`, { bytes: fs.readFileSync(file).toString('base64') });
+        const first = Object.values(d.images)[0];
+        if (!first?.hash)
+            throw new MediumError('meta', '이미지 업로드 응답에 hash가 없어요');
+        return first.hash;
+    }
+    async build(input) {
+        const log = input.log || (() => { });
+        const warnings = [];
+        const placements = [...input.existing];
+        const has = (kind, concept) => placements.find((p) => p.medium === 'meta' && p.kind === kind && (concept ? p.concept === concept : true));
+        const tag = nameTag(input.slug);
+        if (!this.c.pageId)
+            throw new MediumError('meta', '페이지 id가 없어요', '`adpilot connect meta --page <페이지 id>`');
+        const objective = input.goal === 'purchase' ? 'OUTCOME_SALES' : input.goal === 'lead' || input.goal === 'signup' ? (input.pixelId ? 'OUTCOME_SALES' : 'OUTCOME_TRAFFIC') : 'OUTCOME_TRAFFIC';
+        const optimization = input.pixelId && input.goal !== 'traffic' ? 'OFFSITE_CONVERSIONS' : input.pixelId ? 'LANDING_PAGE_VIEWS' : 'LINK_CLICKS';
+        const eventType = input.goal === 'purchase' ? 'PURCHASE' : input.goal === 'lead' ? 'LEAD' : input.goal === 'signup' ? 'COMPLETE_REGISTRATION' : 'CONTENT_VIEW';
+        if (input.validateOnly) {
+            log('  meta: 검증 모드 — 실제 생성 없이 구조만 확인');
+            return { placements, warnings: ['Meta는 서버측 validate_only가 없어 구조·규격·예산만 로컬 검증했어요'] };
+        }
+        // 캠페인(CBO)
+        let camp = has('campaign');
+        if (!camp) {
+            const name = `${tag} ${input.brief.company} · ${input.goal}`;
+            const found = await this.findByName('campaigns', name);
+            const id = found?.id || (await this.call('POST', `${this.c.adAccountId}/campaigns`, { name, objective, status: 'PAUSED', special_ad_categories: [], daily_budget: String(input.dailyBudgetMinor), bid_strategy: 'LOWEST_COST_WITHOUT_CAP', ...(input.endDate ? { stop_time: `${input.endDate}T23:59:00+0900` } : {}) })).id;
+            camp = { medium: 'meta', kind: 'campaign', externalId: id, name, status: 'PAUSED', createdAt: new Date().toISOString() };
+            placements.push(camp);
+            log(`  meta 캠페인 ${found ? '재사용' : '생성'} ${id}`);
+        }
+        // 타겟: 시장 국가 · Advantage+ 오디언스(age_max 금지)
+        const targeting = { geo_locations: { countries: input.markets.map((m) => m.country.toUpperCase()) }, age_min: 18, targeting_automation: { advantage_audience: 1 }, ...(input.markets.length === 1 && input.markets[0].language ? { locales: undefined } : {}) };
+        const domain = new URL(input.landingUrl).hostname;
+        for (const c of input.concepts) {
+            const imgs = input.assets.filter((a) => a.concept === c.key && (a.medium === 'meta' || a.medium === 'both'));
+            if (!imgs.length) {
+                warnings.push(`${c.key}: 메타용 소재가 없어 건너뜀`);
+                continue;
+            }
+            let adset = has('adset', c.key);
+            if (!adset) {
+                const name = `${tag} ${c.key} · ${input.markets.map((m) => m.country).join('+')} · DCO`;
+                const found = await this.findByName('adsets', name);
+                const id = found?.id || (await this.call('POST', `${this.c.adAccountId}/adsets`, { name, campaign_id: camp.externalId, optimization_goal: optimization, billing_event: 'IMPRESSIONS', targeting, status: 'PAUSED', is_dynamic_creative: true, ...(input.pixelId ? { promoted_object: { pixel_id: input.pixelId, custom_event_type: eventType } } : {}) })).id;
+                adset = { medium: 'meta', kind: 'adset', concept: c.key, externalId: id, name, status: 'PAUSED', createdAt: new Date().toISOString() };
+                placements.push(adset);
+                log(`  meta 광고세트 ${c.key} ${found ? '재사용' : '생성'} ${id}`);
+            }
+            let creative = has('creative', c.key);
+            if (!creative) {
+                const hashes = [];
+                for (const a of imgs.filter((x) => [1080].includes(x.w)))
+                    hashes.push(await this.uploadImage(a.file));
+                const name = `${tag} ${c.key} · DCO`;
+                const d = await this.call('POST', `${this.c.adAccountId}/adcreatives`, {
+                    name,
+                    object_story_spec: { page_id: this.c.pageId, ...(this.c.instagramActorId ? { instagram_user_id: this.c.instagramActorId } : {}) },
+                    asset_feed_spec: {
+                        images: hashes.map((h) => ({ hash: h })), bodies: c.bodies.slice(0, 5).map((t) => ({ text: t })), titles: c.headlines.slice(0, 5).map((t) => ({ text: t })), descriptions: c.descriptions.slice(0, 2).map((t) => ({ text: t })),
+                        link_urls: [{ website_url: utm(input.landingUrl, 'meta', input.utmCampaign, c.key), display_url: domain }], call_to_action_types: [c.cta], ad_formats: ['SINGLE_IMAGE'],
+                    },
+                });
+                creative = { medium: 'meta', kind: 'creative', concept: c.key, externalId: d.id, name, status: 'OK', createdAt: new Date().toISOString() };
+                placements.push(creative);
+                log(`  meta 크리에이티브 ${c.key} 생성 ${d.id} (이미지 ${hashes.length})`);
+            }
+            if (!has('ad', c.key)) {
+                const name = `${tag} ${c.key}`;
+                const d = await this.call('POST', `${this.c.adAccountId}/ads`, { name, adset_id: adset.externalId, creative: { creative_id: creative.externalId }, status: 'PAUSED', ...(input.pixelId ? { conversion_domain: domain } : {}) });
+                placements.push({ medium: 'meta', kind: 'ad', concept: c.key, externalId: d.id, name, status: 'PAUSED', createdAt: new Date().toISOString() });
+                log(`  meta 광고 ${c.key} 생성 ${d.id}`);
+            }
+        }
+        return { placements, warnings };
+    }
+    async preview(placements) {
+        const out = [];
+        for (const ad of placements.filter((p) => p.medium === 'meta' && p.kind === 'ad')) {
+            for (const fmt of ['MOBILE_FEED_STANDARD', 'INSTAGRAM_STANDARD']) {
+                try {
+                    const d = await this.call('GET', `${ad.externalId}/previews`, { ad_format: fmt });
+                    if (d.data[0]?.body)
+                        out.push({ concept: ad.concept, name: `Meta · ${fmt === 'INSTAGRAM_STANDARD' ? 'Instagram' : 'Facebook 피드'} · ${ad.concept}`, html: d.data[0].body });
+                }
+                catch (e) {
+                    out.push({ concept: ad.concept, name: `Meta · ${fmt}`, html: `<p>미리보기 실패: ${e instanceof Error ? e.message : e}</p>` });
+                }
+            }
+        }
+        return out;
+    }
+    async setStatus(placements, status) {
+        const order = status === 'ACTIVE' ? ['campaign', 'adset', 'ad'] : ['ad', 'adset', 'campaign'];
+        for (const kind of order)
+            for (const p of placements.filter((x) => x.medium === 'meta' && x.kind === kind)) {
+                await this.call('POST', p.externalId, { status });
+                p.status = status;
+            }
+    }
+    async updateBudget(placements, dailyBudgetMinor) {
+        for (const p of placements.filter((x) => x.medium === 'meta' && x.kind === 'campaign'))
+            await this.call('POST', p.externalId, { daily_budget: String(dailyBudgetMinor) });
+    }
+    async metrics(placements, range) {
+        const camp = placements.find((p) => p.medium === 'meta' && p.kind === 'campaign');
+        if (!camp)
+            return [];
+        const acc = await this.account();
+        const d = await this.call('GET', `${this.c.adAccountId}/insights`, { level: 'ad', fields: 'ad_id,ad_name,adset_id,spend,impressions,clicks,actions', time_range: { since: range.since, until: range.until }, time_increment: 1, filtering: [{ field: 'campaign.id', operator: 'IN', value: [camp.externalId] }], limit: 1000 });
+        const conv = (acts) => (acts || []).filter((a) => ['purchase', 'lead', 'complete_registration', 'offsite_conversion.fb_pixel_purchase', 'offsite_conversion.fb_pixel_lead', 'offsite_conversion.fb_pixel_complete_registration'].includes(a.action_type)).reduce((n, a) => n + Number(a.value), 0);
+        return d.data.map((r) => ({ date: r.date_start, level: 'ad', id: r.ad_id, name: r.ad_name, concept: placements.find((p) => p.externalId === r.ad_id)?.concept, spend: Number(r.spend), impressions: Number(r.impressions), clicks: Number(r.clicks), conversions: conv(r.actions), currency: acc.currency }));
+    }
+    async policy(placements) {
+        const out = [];
+        for (const ad of placements.filter((p) => p.medium === 'meta' && p.kind === 'ad')) {
+            const d = await this.call('GET', ad.externalId, { fields: 'effective_status,issues_info,ad_review_feedback' });
+            const issues = (d.issues_info || []).map((i) => i.error_code === 2446984 ? '광고주 본인 확인 알림(조치 불필요 · 광고 관리자 알림에서 확인 1회)' : `${i.error_summary || ''} ${i.error_message || ''}`.trim());
+            for (const [k, v] of Object.entries(d.ad_review_feedback?.global || {}))
+                issues.push(`정책 거절 ${k}: ${v}`);
+            out.push({ id: ad.externalId, name: ad.name, status: d.effective_status, issues });
+        }
+        return out;
+    }
+    async remove(placements) { for (const p of placements.filter((x) => x.medium === 'meta' && x.kind === 'campaign'))
+        await this.call('DELETE', p.externalId); }
+}

package/dist/adapters/mock.d.ts

@@ -0,0 +1,28 @@
+import type { Placement } from '../core/state.js';
+import { type AccountInfo, type BuildInput, type BuildResult, type CheckItem, type Connector, type InventoryRow, type Medium, type MetricRow, type PolicyRow } from './types.js';
+export declare class MockConnector implements Connector {
+    medium: Medium;
+    private currency;
+    private file;
+    constructor(medium: Medium, currency?: string);
+    private load;
+    private save;
+    private rec;
+    account(): Promise<AccountInfo>;
+    check(): Promise<CheckItem[]>;
+    inventory(): Promise<InventoryRow[]>;
+    build(input: BuildInput): Promise<BuildResult>;
+    preview(placements: Placement[]): Promise<{
+        concept: string | undefined;
+        name: string;
+        html: string;
+    }[]>;
+    setStatus(placements: Placement[], status: 'ACTIVE' | 'PAUSED'): Promise<void>;
+    updateBudget(_p: Placement[], b: number): Promise<void>;
+    metrics(placements: Placement[], range: {
+        since: string;
+        until: string;
+    }): Promise<MetricRow[]>;
+    policy(placements: Placement[]): Promise<PolicyRow[]>;
+    remove(placements: Placement[]): Promise<void>;
+}

package/dist/adapters/mock.js

@@ -0,0 +1,67 @@
+// 모의 어댑터 — ADPILOT_MOCK=1. 실제 매체 호출 없이 전 흐름(e2e)을 돈다. 상태는 ~/.adpilot/mock/<medium>.json.
+import fs from 'node:fs';
+import path from 'node:path';
+import { HOME } from '../core/state.js';
+import { nameTag } from './types.js';
+export class MockConnector {
+    medium;
+    currency;
+    file;
+    constructor(medium, currency = medium === 'meta' ? 'USD' : 'KRW') {
+        this.medium = medium;
+        this.currency = currency;
+        this.file = path.join(HOME, 'mock', `${medium}.json`);
+        fs.mkdirSync(path.dirname(this.file), { recursive: true });
+    }
+    load() { try {
+        return JSON.parse(fs.readFileSync(this.file, 'utf8'));
+    }
+    catch {
+        return { objects: [], calls: [] };
+    } }
+    save(s) { fs.writeFileSync(this.file, JSON.stringify(s, null, 2)); }
+    rec(s) { const st = this.load(); st.calls.push(s); this.save(st); }
+    async account() { return { id: `${this.medium}-mock`, name: `${this.medium} 모의 계정`, currency: this.currency, timezone: 'Asia/Seoul', status: 'ACTIVE' }; }
+    async check() { return [{ key: `${this.medium}.mock`, ok: true, title: '모의 어댑터', detail: '실제 매체 호출 없음' }]; }
+    async inventory() { return this.load().objects.filter((o) => o.kind === 'campaign').map((o) => ({ level: 'campaign', id: o.externalId, name: o.name, status: o.status, spend30d: 0 })); }
+    async build(input) {
+        const st = this.load();
+        const placements = [...input.existing];
+        const tag = nameTag(input.slug);
+        const mk = (kind, concept) => { const existing = placements.find((p) => p.medium === this.medium && p.kind === kind && p.concept === concept); if (existing)
+            return existing; const p = { medium: this.medium, kind, concept, externalId: `${this.medium}_${kind}_${concept || 'root'}_${Math.random().toString(36).slice(2, 8)}`, name: `${tag} ${kind} ${concept || ''}`.trim(), status: 'PAUSED', createdAt: new Date().toISOString() }; placements.push(p); st.objects.push(p); return p; };
+        if (input.validateOnly) {
+            st.calls.push('validate');
+            this.save(st);
+            return { placements: input.existing, warnings: ['모의 검증'] };
+        }
+        mk('campaign');
+        if (this.medium === 'google')
+            mk('adgroup');
+        for (const c of input.concepts) {
+            if (this.medium === 'meta') {
+                mk('adset', c.key);
+                mk('creative', c.key);
+            }
+            mk('ad', c.key);
+        }
+        st.calls.push(`build budget=${input.dailyBudgetMinor} ${input.currency}`);
+        this.save(st);
+        return { placements, warnings: [] };
+    }
+    async preview(placements) { return placements.filter((p) => p.medium === this.medium && p.kind === 'ad').map((p) => ({ concept: p.concept, name: `${this.medium} · ${p.concept}`, html: `<div class="gpreview" data-concept="${p.concept}">mock</div>` })); }
+    async setStatus(placements, status) { for (const p of placements.filter((x) => x.medium === this.medium))
+        p.status = status; this.rec(`status ${status}`); }
+    async updateBudget(_p, b) { this.rec(`budget ${b}`); }
+    async metrics(placements, range) {
+        const ads = placements.filter((p) => p.medium === this.medium && p.kind === 'ad');
+        const out = [];
+        const d0 = new Date(range.since);
+        const d1 = new Date(range.until);
+        for (let d = new Date(d0); d <= d1; d.setDate(d.getDate() + 1))
+            ads.forEach((a, i) => { const imp = 1000 + i * 400; const clicks = Math.round(imp * (0.008 + i * 0.006)); out.push({ date: d.toISOString().slice(0, 10), level: 'ad', id: a.externalId, name: a.name, concept: a.concept, spend: this.currency === 'USD' ? 8 + i : 12000 + i * 1500, impressions: imp, clicks, conversions: i === 1 ? 3 : 1, currency: this.currency }); });
+        return out;
+    }
+    async policy(placements) { return placements.filter((p) => p.medium === this.medium && p.kind === 'ad').map((p) => ({ id: p.externalId, name: p.name, status: 'APPROVED', issues: [] })); }
+    async remove(placements) { const st = this.load(); const ids = new Set(placements.map((p) => p.externalId)); st.objects = st.objects.filter((o) => !ids.has(o.externalId)); st.calls.push('remove'); this.save(st); }
+}

package/dist/adapters/types.d.ts

@@ -0,0 +1,100 @@
+import type { Brief, Concept, CreativeAsset, Goal, Market, Placement } from '../core/state.js';
+export type Medium = 'meta' | 'google';
+export type CheckItem = {
+    key: string;
+    ok: boolean | null;
+    title: string;
+    detail: string;
+    fix?: string;
+    link?: string;
+};
+export type AccountInfo = {
+    id: string;
+    name: string;
+    currency: string;
+    timezone?: string;
+    status?: string;
+    extra?: Record<string, unknown>;
+};
+export type BuildInput = {
+    slug: string;
+    brief: Brief;
+    concepts: Concept[];
+    assets: CreativeAsset[];
+    goal: Goal;
+    markets: Market[];
+    dailyBudgetMinor: number;
+    currency: string;
+    endDate?: string;
+    landingUrl: string;
+    utmCampaign: string;
+    pixelId?: string;
+    conversionActionRn?: string;
+    existing: Placement[];
+    validateOnly?: boolean;
+    log?: (s: string) => void;
+};
+export type BuildResult = {
+    placements: Placement[];
+    warnings: string[];
+};
+export type MetricRow = {
+    date?: string;
+    level: 'campaign' | 'adset' | 'ad';
+    id: string;
+    name: string;
+    concept?: string;
+    spend: number;
+    impressions: number;
+    clicks: number;
+    conversions: number;
+    currency: string;
+};
+export type PolicyRow = {
+    id: string;
+    name: string;
+    status: string;
+    issues: string[];
+};
+export type InventoryRow = {
+    level: 'campaign' | 'adset' | 'ad';
+    id: string;
+    name: string;
+    status: string;
+    effectiveStatus?: string;
+    objective?: string;
+    dailyBudgetMinor?: number;
+    spend30d?: number;
+    impressions30d?: number;
+    clicks30d?: number;
+    parent?: string;
+    issues?: string[];
+};
+export interface Connector {
+    medium: Medium;
+    account(): Promise<AccountInfo>;
+    check(landingUrl?: string): Promise<CheckItem[]>;
+    inventory(): Promise<InventoryRow[]>;
+    build(input: BuildInput): Promise<BuildResult>;
+    preview(placements: Placement[]): Promise<{
+        concept?: string;
+        name: string;
+        html: string;
+    }[]>;
+    setStatus(placements: Placement[], status: 'ACTIVE' | 'PAUSED'): Promise<void>;
+    updateBudget(placements: Placement[], dailyBudgetMinor: number): Promise<void>;
+    metrics(placements: Placement[], range: {
+        since: string;
+        until: string;
+    }): Promise<MetricRow[]>;
+    policy(placements: Placement[]): Promise<PolicyRow[]>;
+    remove?(placements: Placement[]): Promise<void>;
+}
+export declare class MediumError extends Error {
+    medium: Medium;
+    hint?: string | undefined;
+    raw?: unknown | undefined;
+    constructor(medium: Medium, message: string, hint?: string | undefined, raw?: unknown | undefined);
+}
+export declare const utm: (url: string, medium: Medium, campaign: string, content: string) => string;
+export declare const nameTag: (slug: string) => string;

package/dist/adapters/types.js

@@ -0,0 +1,20 @@
+export class MediumError extends Error {
+    medium;
+    hint;
+    raw;
+    constructor(medium, message, hint, raw) {
+        super(message);
+        this.medium = medium;
+        this.hint = hint;
+        this.raw = raw;
+    }
+}
+export const utm = (url, medium, campaign, content) => {
+    const u = new URL(url);
+    u.searchParams.set('utm_source', medium === 'meta' ? 'meta' : 'google');
+    u.searchParams.set('utm_medium', medium === 'meta' ? 'paid_social' : 'display');
+    u.searchParams.set('utm_campaign', campaign);
+    u.searchParams.set('utm_content', content);
+    return u.toString();
+};
+export const nameTag = (slug) => `[adp:${slug}]`;

package/dist/cli.d.ts

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