adyou 0.6.18 → 0.7.1

package/dist/adapters/google.d.ts

@@ -14,6 +14,11 @@ export declare class GoogleConnector implements Connector {
     private search;
     listAccessible(): Promise<string[]>;
     account(): Promise<AccountInfo>;
+    /** 이 커넥터의 customerId(= MCC · loginCustomerId 도 MCC) 아래 하위 광고 계정 만들기 — 대행 모드 고객당 계정. 실측(2026-09-25): SA 가 MCC 에서 ADMIN 이어야 함(STANDARD 면 ACTION_NOT_PERMITTED) ·
+     *  계정은 삭제 불가(화면에서 해지만) · 🔴 결제 연결은 API 불가(billingSetups → NO_SIGNUP_PERMISSION · SA 는 결제 프로필 사용자가 될 수 없음) → 운영자가 화면에서 결제 프로필을 붙인다. */
+    createClientAccount(name: string, currency?: string, timeZone?: string): Promise<string>;
+    /** 결제가 연결돼 광고가 나갈 수 있는 계정인지(billing_setup APPROVED) */
+    billingApproved(): Promise<boolean>;
     check(): Promise<CheckItem[]>;
     inventory(): Promise<InventoryRow[]>;
     private uploadImage;

package/dist/adapters/google.js

@@ -34,7 +34,8 @@ export class GoogleConnector {
         const headers = { authorization: `Bearer ${await this.accessToken()}`, 'content-type': 'application/json' };
         if (this.c.loginCustomerId)
             headers['login-customer-id'] = this.c.loginCustomerId;
-        const res = await fetch(`${API}/customers/${cid}/${path}`, { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(120_000) });
+        // `:createCustomerClient` 처럼 콜론으로 시작하는 메서드는 고객 경로에 바로 붙는다(슬래시 없음)
+        const res = await fetch(`${API}/customers/${cid}${path.startsWith(':') ? '' : '/'}${path}`, { method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(120_000) });
         const data = (await res.json().catch(() => ({})));
         if (!res.ok || data.error)
             throw this.wrap(data.error, path);
@@ -82,6 +83,20 @@ export class GoogleConnector {
             throw new MediumError('google', '고객 정보를 읽지 못했어요');
         return { id: c.id, name: c.descriptiveName || c.id, currency: c.currencyCode, timezone: c.timeZone, status: c.status, extra: { manager: c.manager } };
     }
+    /** 이 커넥터의 customerId(= MCC · loginCustomerId 도 MCC) 아래 하위 광고 계정 만들기 — 대행 모드 고객당 계정. 실측(2026-09-25): SA 가 MCC 에서 ADMIN 이어야 함(STANDARD 면 ACTION_NOT_PERMITTED) ·
+     *  계정은 삭제 불가(화면에서 해지만) · 🔴 결제 연결은 API 불가(billingSetups → NO_SIGNUP_PERMISSION · SA 는 결제 프로필 사용자가 될 수 없음) → 운영자가 화면에서 결제 프로필을 붙인다. */
+    async createClientAccount(name, currency = 'KRW', timeZone = 'Asia/Seoul') {
+        const d = await this.call(':createCustomerClient', { customerClient: { descriptiveName: name.slice(0, 100), currencyCode: currency, timeZone } });
+        const id = d.resourceName?.split('/')[1];
+        if (!id)
+            throw new MediumError('google', '하위 계정 ID 를 받지 못했어요');
+        return id;
+    }
+    /** 결제가 연결돼 광고가 나갈 수 있는 계정인지(billing_setup APPROVED) */
+    async billingApproved() {
+        const rows = await this.search('SELECT billing_setup.status FROM billing_setup');
+        return rows.some((r) => r.billingSetup.status === 'APPROVED');
+    }
     async check() {
         const items = [];
         let accessible = [];

package/dist/adapters/meta-targeting.d.ts

@@ -0,0 +1,37 @@
+export type AudienceHint = {
+    ageRange?: string;
+    gender?: string;
+};
+export type TargetingInput = {
+    countries: string[];
+    lang?: string;
+    audience?: AudienceHint;
+    strict?: boolean;
+};
+export type MetaTargeting = {
+    geo_locations: {
+        countries: string[];
+    };
+    age_min: number;
+    age_max?: number;
+    genders?: number[];
+    locales?: number[];
+    targeting_automation: {
+        advantage_audience: 0 | 1;
+    };
+};
+export type TargetingResult = {
+    targeting: MetaTargeting;
+    regionalCategories: string[];
+    notes: string[];
+};
+/** 나라 기본 언어 — 시장 언어가 이것과 다르면 「그 나라에 사는 다른 언어 사용자」(디아스포라) 로 보고 locales 를 건다 */
+export declare const COUNTRY_LANG: Record<string, string>;
+/** 메타 광고 locale id — 「전체」 묶음이 있는 언어는 그것(영어 1001 · 중국어 1004 · 스페인어 1002 · 포르투갈어 1003) */
+export declare const META_LOCALE: Record<string, number[]>;
+/** "25-34" · "18~34" · "20대" · "25+" · "30s" → [min, max] (18~65 로 자름 · 못 읽으면 null) */
+export declare function parseAgeRange(s?: string): {
+    min: number;
+    max?: number;
+} | null;
+export declare function metaTargeting(i: TargetingInput): TargetingResult;

package/dist/adapters/meta-targeting.js

@@ -0,0 +1,66 @@
+/** 나라 기본 언어 — 시장 언어가 이것과 다르면 「그 나라에 사는 다른 언어 사용자」(디아스포라) 로 보고 locales 를 건다 */
+export const COUNTRY_LANG = {
+    KR: 'ko', JP: 'ja', CN: 'zh', TW: 'zh', HK: 'zh', MO: 'zh', SG: 'en', MY: 'ms', US: 'en', GB: 'en', CA: 'en', AU: 'en', NZ: 'en', IE: 'en',
+    DE: 'de', AT: 'de', CH: 'de', FR: 'fr', BE: 'fr', ES: 'es', MX: 'es', AR: 'es', CL: 'es', CO: 'es', PE: 'es', IT: 'it', BR: 'pt', PT: 'pt',
+    TH: 'th', VN: 'vi', ID: 'id', RU: 'ru', NL: 'nl', PL: 'pl', TR: 'tr', SE: 'sv', NO: 'no', DK: 'da', FI: 'fi', IN: 'en', PH: 'en',
+};
+/** 메타 광고 locale id — 「전체」 묶음이 있는 언어는 그것(영어 1001 · 중국어 1004 · 스페인어 1002 · 포르투갈어 1003) */
+export const META_LOCALE = {
+    ko: [12], ja: [11], zh: [1004], en: [1001], es: [1002], pt: [1003], de: [5], fr: [9], it: [10], th: [35], vi: [27], id: [25], ru: [17], nl: [14], pl: [15], tr: [19], sv: [26], da: [33], fi: [37], no: [34],
+};
+const REGULATED = { TW: 'TAIWAN_UNIVERSAL', SG: 'SINGAPORE_UNIVERSAL' };
+/** "25-34" · "18~34" · "20대" · "25+" · "30s" → [min, max] (18~65 로 자름 · 못 읽으면 null) */
+export function parseAgeRange(s) {
+    if (!s)
+        return null;
+    const t = s.replace(/\s/g, '');
+    let m = t.match(/(\d{2})\s*[-~–—]\s*(\d{2})/);
+    if (m) {
+        const a = Number(m[1]), b = Number(m[2]);
+        return { min: clamp(Math.min(a, b)), max: clamp(Math.max(a, b)) };
+    }
+    m = t.match(/(\d{2})\+/);
+    if (m)
+        return { min: clamp(Number(m[1])) };
+    m = t.match(/(\d)0(대|s)/);
+    if (m) {
+        const d = Number(m[1]) * 10;
+        return { min: clamp(d), max: clamp(d + 9) };
+    }
+    m = t.match(/^(\d{2})$/);
+    if (m)
+        return { min: clamp(Number(m[1])) };
+    return null;
+}
+const clamp = (n) => Math.max(18, Math.min(65, n));
+export function metaTargeting(i) {
+    const countries = [...new Set(i.countries.map((c) => c.toUpperCase()))];
+    const notes = [];
+    const t = { geo_locations: { countries }, age_min: 18, targeting_automation: { advantage_audience: 1 } };
+    const lang = (i.lang || '').split('-')[0];
+    // ① 디아스포라 → locales(그 언어를 쓰는 사용자만). 나라 전부가 그 언어를 기본으로 쓰면 걸지 않는다(도달 손실만 있음).
+    if (lang && countries.some((c) => (COUNTRY_LANG[c] || '') !== lang) && META_LOCALE[lang]) {
+        t.locales = META_LOCALE[lang];
+        notes.push(`${countries.filter((c) => (COUNTRY_LANG[c] || '') !== lang).join('+')}의 ${lang} 사용자만(언어 설정 기준)`);
+    }
+    // ② 규제 카테고리(대만·싱가포르 보편 규제 · 없으면 광고세트 생성이 거절됨)
+    const regionalCategories = countries.map((c) => REGULATED[c]).filter(Boolean);
+    // ③ 브리프 오디언스 → 연령·성별
+    const age = parseAgeRange(i.audience?.ageRange);
+    if (age)
+        t.age_min = age.min;
+    const g = (i.audience?.gender || '').toLowerCase();
+    if (i.strict) {
+        t.targeting_automation = { advantage_audience: 0 };
+        if (age?.max)
+            t.age_max = age.max;
+        if (g === 'female' || g === '여' || g === '여성' || g === 'f')
+            t.genders = [2];
+        else if (g === 'male' || g === '남' || g === '남성' || g === 'm')
+            t.genders = [1];
+        notes.push(`타겟 고정: ${t.age_min}${t.age_max ? `~${t.age_max}` : '+'}세${t.genders ? (t.genders[0] === 2 ? ' · 여성' : ' · 남성') : ''}(Advantage+ 오디언스 끔)`);
+    }
+    else if (age)
+        notes.push(`최소 연령 ${age.min}세(Advantage+ 오디언스 · 상한은 매체가 넓힘${age.max ? ` · 브리프 상한 ${age.max}세는 strict 에서만 강제` : ''})`);
+    return { targeting: t, regionalCategories, notes };
+}

package/dist/adapters/meta.js

@@ -2,6 +2,7 @@
 //   예산=계정 통화 최소 단위 · Advantage+ 오디언스에선 age_max 금지 · DCO 광고세트엔 광고 1개(컨셉=광고세트) · instagram_user_id · WITH_ISSUES 2446984는 조치 불필요
 //   앱 개발 모드면 크리에이티브 생성 100 오류 · 픽셀 트래픽 권한 밖 도메인은 이벤트 조용히 폐기(signals/config blockReason)
 import fs from 'node:fs';
+import { metaTargeting } from './meta-targeting.js';
 import { abKey, langGroups, localizedCopy, 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'];
@@ -200,8 +201,24 @@ export class MetaConnector {
             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 } : {}) };
+        // 타겟: 언어 그룹별 — 디아스포라 locales · 대만/싱가포르 규제 카테고리 · 브리프 오디언스(meta-targeting.ts · 밈튜브 하네스 학습 2026-09-23)
+        const targetFor = (g) => metaTargeting({ countries: g.countries, lang: g.lang, audience: input.audience, strict: input.strictAudience });
+        /** 광고세트 생성 — locales id 가 거절되면 locales 없이 1회 재시도(도달만 넓어짐 · 생성은 성공) */
+        const createAdset = async (body, tr) => {
+            const base = { ...body, targeting: tr.targeting, ...(tr.regionalCategories.length ? { regional_regulated_categories: tr.regionalCategories } : {}) };
+            try {
+                return (await this.call('POST', `${this.c.adAccountId}/adsets`, base)).id;
+            }
+            catch (e) {
+                if (tr.targeting.locales && /locale/i.test(e instanceof Error ? e.message : String(e))) {
+                    const { locales: _l, ...rest } = tr.targeting;
+                    void _l;
+                    log('  ⚠ 언어(locale) 타겟이 거절돼 언어 없이 만들어요');
+                    return (await this.call('POST', `${this.c.adAccountId}/adsets`, { ...base, targeting: rest })).id;
+                }
+                throw e;
+            }
+        };
         const domain = new URL(input.landingUrl).hostname;
         // 언어 그룹 — 같은 언어를 쓰는 나라끼리 광고세트를 나눠 그 언어 문구·자막 소재만 넣는다(언어 섞임 방지 · 시장별 성과 비교)
         const groups = langGroups(input.markets, input.brief.language);
@@ -217,14 +234,16 @@ export class MetaConnector {
                     warnings.push(`${c.key}${lt}: 메타용 소재가 없어 건너뜀`);
                     continue;
                 }
-                const gTargeting = { ...targeting, geo_locations: { countries: g.countries } };
+                const gT = targetFor(g);
+                if (c === input.concepts[0] && gT.notes.length)
+                    log(`  타겟 ${g.countries.join('+')}: ${gT.notes.join(' · ')}${gT.regionalCategories.length ? ` · 규제 카테고리 ${gT.regionalCategories.join(',')}` : ''}`);
                 const gl = groups.length > 1 ? L : undefined;
                 if (imgs.length) {
                     let adset = has('adset', c.key, 'image', gl);
                     if (!adset) {
                         const name = `${tag} ${c.key} · ${g.countries.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: gTargeting, status: 'PAUSED', is_dynamic_creative: true, ...(input.pixelId ? { promoted_object: { pixel_id: input.pixelId, custom_event_type: eventType } } : {}) })).id;
+                        const id = found?.id || (await createAdset({ name, campaign_id: camp.externalId, optimization_goal: optimization, billing_event: 'IMPRESSIONS', status: 'PAUSED', is_dynamic_creative: true, ...(input.pixelId ? { promoted_object: { pixel_id: input.pixelId, custom_event_type: eventType } } : {}) }, gT));
                         adset = { medium: 'meta', kind: 'adset', concept: c.key, ...(gl ? { lang: gl } : {}), externalId: id, name, status: 'PAUSED', createdAt: new Date().toISOString() };
                         placements.push(adset);
                         log(`  meta 광고세트 ${c.key}${lt} ${found ? '재사용' : '생성'} ${id}`);
@@ -260,7 +279,7 @@ export class MetaConnector {
                     if (!adset) {
                         const name = `${tag} ${c.key} · ${g.countries.join('+')} · VIDEO`;
                         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: gTargeting, status: 'PAUSED', is_dynamic_creative: true, ...(input.pixelId ? { promoted_object: { pixel_id: input.pixelId, custom_event_type: eventType } } : {}) })).id;
+                        const id = found?.id || (await createAdset({ name, campaign_id: camp.externalId, optimization_goal: optimization, billing_event: 'IMPRESSIONS', status: 'PAUSED', is_dynamic_creative: true, ...(input.pixelId ? { promoted_object: { pixel_id: input.pixelId, custom_event_type: eventType } } : {}) }, gT));
                         adset = { medium: 'meta', kind: 'adset', concept: c.key, format: 'video', ...(gl ? { lang: gl } : {}), externalId: id, name, status: 'PAUSED', createdAt: new Date().toISOString() };
                         placements.push(adset);
                         log(`  meta 영상 광고세트 ${c.key}${lt} ${found ? '재사용' : '생성'} ${id}`);
@@ -334,7 +353,7 @@ export class MetaConnector {
         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,video_play_actions,video_thruplay_watched_actions,video_p50_watched_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, format: placements.find((p) => p.externalId === r.ad_id)?.format || 'image', lang: placements.find((p) => p.externalId === r.ad_id)?.lang, spend: Number(r.spend), impressions: Number(r.impressions), clicks: Number(r.clicks), conversions: conv(r.actions), videoPlays: Number(r.video_play_actions?.[0]?.value || 0) || undefined, thruplays: Number(r.video_thruplay_watched_actions?.[0]?.value || 0) || undefined, videoP50: Number(r.video_p50_watched_actions?.[0]?.value || 0) || undefined, currency: acc.currency }));
+        return d.data.map((r) => ({ date: r.date_start, level: 'ad', id: r.ad_id, name: r.ad_name, adsetId: r.adset_id, concept: placements.find((p) => p.externalId === r.ad_id)?.concept, format: placements.find((p) => p.externalId === r.ad_id)?.format || 'image', lang: placements.find((p) => p.externalId === r.ad_id)?.lang, spend: Number(r.spend), impressions: Number(r.impressions), clicks: Number(r.clicks), conversions: conv(r.actions), videoPlays: Number(r.video_play_actions?.[0]?.value || 0) || undefined, thruplays: Number(r.video_thruplay_watched_actions?.[0]?.value || 0) || undefined, videoP50: Number(r.video_p50_watched_actions?.[0]?.value || 0) || undefined, currency: acc.currency }));
     }
     async policy(placements) {
         const out = [];

package/dist/adapters/types.d.ts

@@ -32,6 +32,12 @@ export type BuildInput = {
     conversionActionRn?: string;
     existing: Placement[];
     validateOnly?: boolean;
+    /** 브리프 오디언스(연령대·성별) → 메타 타겟 · strict 면 Advantage+ 를 끄고 상한·성별 강제(meta-targeting.ts) */
+    audience?: {
+        ageRange?: string;
+        gender?: string;
+    };
+    strictAudience?: boolean;
     log?: (s: string) => void;
 };
 export type BuildResult = {
@@ -45,7 +51,8 @@ export type MetricRow = {
     name: string;
     concept?: string;
     format?: 'image' | 'video';
-    lang?: string; /** 영상: 재생 수 · 완주(ThruPlay · 15초 또는 끝까지) · 50% 시청 — 훅률·완주율 계산 */
+    lang?: string; /** 광고세트(비교 묶음) */
+    adsetId?: string; /** 영상: 재생 수 · 완주(ThruPlay · 15초 또는 끝까지) · 50% 시청 — 훅률·완주율 계산 */
     videoPlays?: number;
     thruplays?: number;
     videoP50?: number;

package/dist/cli.js

@@ -104,10 +104,10 @@ program.command('brief <url>').description('사이트 읽고 브리프 만들기
         die(e);
     }
 });
-program.command('creatives').description('컨셉·카피 + 이미지 생성 + 12규격 합성 + 규격 검사').option('--concepts <n>', '컨셉 수', '3').option('--feedback <text>', '자연어 수정(「더 고급스럽게」) — 전부 다시 만든다').option('--images <folder>', '직접 준비한 배경 이미지 폴더').option('--no-images', '이미지 생성 없이 브랜드 그래디언트').option('--force', '다시 만들기').option('--mode <mode>', '소재 형태 auto|image|video|text').option('--video', '영상 소재도 만든다(9:16 8초 · Veo 3.1 · 소리 포함)').option('--video-seconds <n>', '영상 길이 8|15|30 (15/30 은 Seedance 2.5)').option('--requirements <text>', '요구사항·방향(참고 이미지는 --images 폴더)').action(async (o) => {
+program.command('creatives').description('컨셉·카피 + 이미지 생성 + 12규격 합성 + 규격 검사').option('--concepts <n>', '컨셉 수', '3').option('--feedback <text>', '자연어 수정(「더 고급스럽게」) — 전부 다시 만든다').option('--images <folder>', '직접 준비한 배경 이미지 폴더').option('--videos <folder>', '제품이 실제로 만든 영상 폴더(mp4) — 생성 없이 훅·자막·CTA·엔드카드·몽타주로 광고 제작(비용 0)').option('--no-images', '이미지 생성 없이 브랜드 그래디언트').option('--force', '다시 만들기').option('--mode <mode>', '소재 형태 auto|image|video|text').option('--video', '영상 소재도 만든다(9:16 8초 · Veo 3.1 · 소리 포함)').option('--video-seconds <n>', '영상 길이 8|15|30 (15/30 은 Seedance 2.5)').option('--requirements <text>', '요구사항·방향(참고 이미지는 --images 폴더)').action(async (o) => {
     try {
         const p = resolveProject(program.opts().project);
-        const { project, report } = await opCreatives(p, { count: Number(o.concepts), feedback: o.feedback, images: o.images, noImages: o.images === false, force: o.force, mode: o.mode, video: o.video, videoSeconds: o.videoSeconds ? Number(o.videoSeconds) : undefined, requirements: o.requirements, log });
+        const { project, report } = await opCreatives(p, { count: Number(o.concepts), feedback: o.feedback, images: o.images, videos: o.videos, noImages: o.images === false, force: o.force, mode: o.mode, video: o.video, videoSeconds: o.videoSeconds ? Number(o.videoSeconds) : undefined, requirements: o.requirements, log });
         log(`\n컨셉 ${project.concepts.length}개 · 소재 ${project.assets.filter((a) => a.concept !== '_logo').length}장`);
         for (const c of project.concepts)
             log(`  · ${c.name}(${c.key}) — ${c.headlines[0]}`);

package/dist/core/creatives/factory.d.ts

@@ -29,3 +29,24 @@ export type FactoryInput = {
 export declare function renderEndCard(dir: string, brief: Brief, concept: Concept, ratio: VideoRatio, lang: string, backgrounds?: Record<string, string | null>): Promise<string | null>;
 /** 컨셉의 영상 소재 전부(포맷 × 언어 × 비율) — 실패한 포맷은 건너뛰고 로그 · 성공한 건마다 onAsset */
 export declare function produceConceptVideos(o: FactoryInput): Promise<VideoAsset[]>;
+export type FootageInput = {
+    dir: string;
+    brief: Brief;
+    concept: Concept;
+    clips: string[];
+    langs?: string[];
+    goal?: Goal;
+    /** 원본 1편당 최대 길이(초 · 기본 20) · 몽타주 컷 길이(기본 4.5) */
+    maxSec?: number;
+    montageCutSec?: number;
+    montage?: boolean;
+    captions?: boolean;
+    endCard?: boolean;
+    log?: FactoryLog;
+    onAsset?: (a: VideoAsset) => void | Promise<void>;
+};
+export declare const FOOTAGE_FORMATS: {
+    readonly single: "footage";
+    readonly montage: "montage";
+};
+export declare function produceFootageVideos(o: FootageInput): Promise<VideoAsset[]>;

package/dist/core/creatives/factory.js

@@ -7,9 +7,9 @@ import path from 'node:path';
 import { DERIVED_RATIOS, RETAKE_CAP_RATIO, VIDEO_DIMS, hasSeedance, speechVideoModel } from './media.js';
 import { genreStyle, PACE, SCENE_FORMATS, TONE_WORDS } from './playbook.js';
 import { ctaLabel, renderConcept, renderOverlay, renderPhoneStage } from './render.js';
-import { langName, localizedBoard, localizedConcept, planStoryboards, translateCopy } from './storyboard.js';
+import { fitHook, langName, localizedBoard, localizedConcept, planStoryboards, translateCopy } from './storyboard.js';
 import { generateVideo } from './video.js';
-import { appendEndCard, burnCaptions, concatClips, deriveRatio, hasFfmpeg, kenBurnsClip, lastFrame, mixVoiceover, motionScore, pickHookBand, probe, refCanvas, tailLoudnessDb, uiDemoClip } from './videofx.js';
+import { appendEndCard, burnCaptions, concatClips, deriveRatio, hasFfmpeg, kenBurnsClip, lastFrame, mixVoiceover, motionScore, normalize, pickHookBand, probe, refCanvas, tailLoudnessDb, trimClip, uiDemoClip } from './videofx.js';
 import { synthesizeSpeech, ttsAvailable } from './tts.js';
 import { spokenForm } from './speech.js';
 import { isMockGen } from './images.js';
@@ -409,3 +409,125 @@ export async function produceConceptVideos(o) {
     }
     return out;
 }
+export const FOOTAGE_FORMATS = { single: 'footage', montage: 'montage' };
+export async function produceFootageVideos(o) {
+    const log = o.log || (() => { });
+    const c = o.concept;
+    const out = [];
+    const ff = await hasFfmpeg();
+    const baseLang = o.brief.language || 'ko';
+    const langs = o.langs?.length ? [...new Set(o.langs)] : [baseLang];
+    const ratio = '9x16';
+    const dims = VIDEO_DIMS[ratio];
+    const maxSec = o.maxSec ?? 20;
+    const cut = o.montageCutSec ?? 4.5;
+    const clips = o.clips.filter((f) => fs.existsSync(f)).slice(0, 4);
+    if (!clips.length) {
+        log('  ⚠ 실제 산출물 영상이 없어요');
+        return out;
+    }
+    if (!ff) {
+        log('  ⚠ ffmpeg 가 없어 원본을 그대로 써요');
+        for (const [i, f] of clips.entries()) {
+            const a = { concept: c.key, w: dims.w, h: dims.h, ratio, file: f, medium: 'meta', type: 'video', durationSec: 0, mime: 'video/mp4', costKrw: 0, origin: 'upload', format: FOOTAGE_FORMATS.single, lang: langs[0], variant: `footage_${i}` };
+            out.push(a);
+            await o.onAsset?.(a);
+        }
+        return out;
+    }
+    // 시장 언어 번역(문구) — 콘티가 없으므로 헤드라인·본문만 옮긴다(이미 있으면 재사용)
+    const extra = langs.filter((l) => l.split('-')[0] !== baseLang.split('-')[0]);
+    if (extra.length && (!c.i18n || extra.some((l) => !c.i18n[l]))) {
+        try {
+            log(`  ${extra.map(langName).join('·')} 로 문구 옮기는 중…`);
+            c.i18n = { ...(c.i18n || {}), ...(await translateCopy(o.brief, c, c.storyboards || [], extra)) };
+        }
+        catch (e) {
+            log(`  ⚠ 번역 실패(원문 사용): ${e instanceof Error ? e.message.slice(0, 120) : e}`);
+        }
+    }
+    // 원본 정규화(9:16 cover · ≤maxSec) — 같은 원본은 컨셉이 달라도 한 번만
+    const raws = [];
+    for (const [i, f] of clips.entries()) {
+        const raw = path.join(o.dir, `footage_${i}_${ratio}.raw.mp4`);
+        try {
+            if (!fs.existsSync(raw))
+                await normalize(f, raw, ratio, maxSec);
+            raws.push({ file: raw, idx: i });
+        }
+        catch (e) {
+            log(`  ⚠ 원본 ${i + 1} 정규화 실패: ${e instanceof Error ? e.message.slice(0, 120) : e}`);
+        }
+    }
+    const pieces = raws.map((r) => ({ key: `${c.key}_footage${r.idx}`, format: FOOTAGE_FORMATS.single, raw: r.file, variant: `footage_${r.idx}` }));
+    // 몽타주 — 원본 2편 이상이면 각 t0=1.0 에서 cut 초씩(최대 3) 하드컷
+    if ((o.montage ?? true) && raws.length >= 2) {
+        try {
+            const segs = [];
+            for (const r of raws.slice(0, 3)) {
+                const s = path.join(o.dir, `montage_seg_${r.idx}.mp4`);
+                if (!fs.existsSync(s))
+                    await trimClip(r.file, s, { t0: 1.0, sec: cut });
+                segs.push(s);
+            }
+            const mont = path.join(o.dir, `${c.key}_montage_${ratio}.raw.mp4`);
+            if (!fs.existsSync(mont))
+                await concatClips(segs, mont, dims);
+            pieces.push({ key: `${c.key}_montage`, format: FOOTAGE_FORMATS.montage, raw: mont, variant: 'montage' });
+        }
+        catch (e) {
+            log(`  ⚠ 몽타주 실패: ${e instanceof Error ? e.message.slice(0, 120) : e}`);
+        }
+    }
+    log(`「${c.name}」 실제 산출물 ${raws.length}편${pieces.length > raws.length ? ' + 몽타주 1' : ''} → 훅·자막·CTA·엔드카드(언어 ${langs.join('·')} · 생성 비용 0)`);
+    for (const pc of pieces) {
+        for (const lang of langs) {
+            const lc = localizedConcept(c, c.i18n, lang);
+            const cta = ctaLabel(c.cta, lang);
+            // 훅 = 헤드라인 1 · 자막 = 영상 자막 줄(브리프 언어) 또는 헤드라인 2~3 · 몽타주는 자막을 끝까지
+            const lines = (lang === baseLang && c.videoLines?.length ? c.videoLines : lc.headlines.slice(1, 3)).filter(Boolean);
+            const text = { hook: fitHook(lc.headlines[0] || c.headlines[0] || ''), captions: lines.slice(0, 3) };
+            const ratios = [ratio, ...DERIVED_RATIOS[ratio]];
+            for (const r of ratios) {
+                const d = VIDEO_DIMS[r];
+                const finalFile = path.join(o.dir, `${pc.key}_${lang}_${r}.mp4`);
+                let cur = pc.raw;
+                let durationSec = 0;
+                try {
+                    const pr0 = await probe(pc.raw);
+                    durationSec = pr0.durationSec;
+                    if (r !== ratio) {
+                        const df = path.join(o.dir, `${pc.key}_${r}.raw.mp4`);
+                        if (!fs.existsSync(df))
+                            await deriveRatio(pc.raw, df, r);
+                        cur = df;
+                    }
+                    if (o.captions ?? true) {
+                        const layout = await pickHookBand(cur);
+                        const withCap = path.join(o.dir, `${pc.key}_${lang}_${r}.cap.mp4`);
+                        await burnCaptions(cur, withCap, { overlays: await overlaysFor(o.dir, pc.key, d, text, cta, o.brief.palette.primary, durationSec, lang, layout) });
+                        cur = withCap;
+                    }
+                    if (o.endCard ?? true) {
+                        const card = await renderEndCard(o.dir, o.brief, lc, r, lang, {});
+                        if (card) {
+                            const withEnd = path.join(o.dir, `${pc.key}_${lang}_${r}.end.mp4`);
+                            await appendEndCard(cur, card, withEnd, 2);
+                            cur = withEnd;
+                            durationSec += 2;
+                        }
+                    }
+                }
+                catch (e) {
+                    log(`  ⚠ ${pc.variant} ${lang} ${r} 마감 실패(원본 사용): ${e instanceof Error ? e.message.slice(0, 160) : e}`);
+                }
+                fs.copyFileSync(cur, finalFile);
+                const asset = { concept: c.key, w: d.w, h: d.h, ratio: r, file: finalFile, medium: 'meta', type: 'video', durationSec: Math.round(durationSec), mime: 'video/mp4', costKrw: 0, origin: 'upload', format: pc.format, lang, variant: `${pc.variant}_${lang}` };
+                out.push(asset);
+                await o.onAsset?.(asset);
+            }
+        }
+    }
+    log(`  실제 산출물 광고 ${out.length}편 완성(원본 ${raws.length} × 언어 ${langs.length} × 비율 3${pieces.length > raws.length ? ' + 몽타주' : ''}) · 생성 원가 ₩0`);
+    return out;
+}

package/dist/core/creatives/media.d.ts

@@ -1,7 +1,8 @@
 import type { Medium } from '../../adapters/types.js';
 import { type Tone, type VideoFormat } from './playbook.js';
 export type CreativeMode = 'auto' | 'image' | 'video' | 'text';
-export type CreativeSource = 'ai' | 'guided' | 'manual';
+/** product = 제품이 실제로 만든 결과물(사용자 산출물·데모 영상 URL)을 편집 구조로 감싸 광고로(생성 비용 0 · 밈튜브 하네스 학습 2026-09-23) */
+export type CreativeSource = 'ai' | 'guided' | 'manual' | 'product';
 export type Tier = 'economy' | 'standard' | 'premium';
 export type VideoRatio = '9x16' | '16x9' | '1x1' | '4x5';
 export type VideoProvider = 'auto' | 'veo' | 'seedance';
@@ -37,6 +38,10 @@ export type CreativeSpec = {
         bodies?: string[];
         descriptions?: string[];
     };
+    /** product: 실제 산출물 영상 URL(≤10 · mp4/mov/webm) — 내려받아 훅·자막·CTA·엔드카드·몽타주로 감싼다 */
+    footageUrls?: string[];
+    /** 메타 타겟 — auto(기본 · Advantage+ 안에서 최소 연령·언어만) · strict(브리프 연령대 상한·성별 강제 · Advantage+ 끔) */
+    audience?: 'auto' | 'strict';
 };
 export type VideoJob = {
     ratio: VideoRatio;

package/dist/core/creatives/media.js

@@ -31,7 +31,7 @@ export function pickVideoModel(durationSec, tier, provider = 'auto', ratio = '9x
 }
 const FORMAT_LABEL_SHORT = { ugc_selfie: '셀카 후기', ui_demo: '화면 데모', cinematic: '시네마틱', product_hero: '제품', lifestyle: '라이프스타일', text_hook: '글자 훅' };
 export const MODE_LABEL = { image: '이미지 + 문구(기본)', auto: '이미지 + 영상(베타)', video: '영상 위주(베타)', text: '글·링크 위주' };
-export const SOURCE_LABEL = { ai: 'AI가 전부 만들기', guided: '내 요구사항·참고 이미지로', manual: '직접 올린 소재로' };
+export const SOURCE_LABEL = { ai: 'AI가 전부 만들기', guided: '내 요구사항·참고 이미지로', manual: '직접 올린 소재로', product: '실제 산출물 영상으로(URL)' };
 /**
  * 설정 + 예산 → 실행 계획. 온라인 광고 소재의 일반 배합:
  *  - 이미지는 컨셉마다 비율 4종(1:1·4:5·9:16·16:9) 배경을 만들어 12규격으로 합성(기존) · 「이미지 위주」는 배경 2세트(A/B)
@@ -49,14 +49,15 @@ export function resolveCreativePlan(spec, ctx) {
     const mode = s.mode || 'image';
     const source = s.source || 'ai';
     const small = ctx.monthlyKrw < 500_000;
-    const concepts = Math.max(1, Math.min(5, s.concepts || (source === 'manual' ? 1 : mode === 'text' ? 4 : 3)));
+    const concepts = Math.max(1, Math.min(5, s.concepts || (source === 'manual' ? 1 : source === 'product' ? 2 : mode === 'text' ? 4 : 3)));
     const imgTier = s.images?.tier || (ctx.monthlyKrw >= 3_000_000 ? 'standard' : 'economy');
-    const imagesEnabled = source !== 'manual' && mode !== 'text';
+    // product: 이미지 배경은 실제 산출물의 프레임(생성 0) · 영상은 생성하지 않고 산출물을 감싼다
+    const imagesEnabled = source !== 'manual' && source !== 'product' && mode !== 'text';
     const variants = Math.max(1, Math.min(3, s.images?.variants || (mode === 'image' ? 2 : 1)));
     const ratios = ['1x1', '4x5', '9x16', '16x9'];
     const vTier = s.video?.tier || (ctx.monthlyKrw >= 2_000_000 ? 'standard' : 'economy');
     const duration = s.video?.durationSec || 8;
-    const wantVideo = source !== 'manual' && s.video?.count !== 0 && mode !== 'text' && (mode === 'auto' || mode === 'video' || (s.video?.count || 0) > 0 || (s.video?.formats?.length || 0) > 0);
+    const wantVideo = source !== 'manual' && source !== 'product' && s.video?.count !== 0 && mode !== 'text' && (mode === 'auto' || mode === 'video' || (s.video?.count || 0) > 0 || (s.video?.formats?.length || 0) > 0);
     const vRatios = s.video?.ratios?.length ? s.video.ratios : ['9x16'];
     const pb = playbookFor(ctx.industry);
     const tone = s.tone || pb.tone;
@@ -91,6 +92,8 @@ export function resolveCreativePlan(spec, ctx) {
         lines.push(`이미지 배경 ${concepts * variants * ratios.length}장(방향 ${concepts} × 세트 ${variants} × 비율 4) ≈ ₩${imagesKrw.toLocaleString()} → 12가지 크기로 합성(합성은 무료)`);
     else if (source === 'manual')
         lines.push('이미지·영상은 올려 주신 것을 그대로 써요(생성 비용 0)');
+    else if (source === 'product')
+        lines.push(`실제 산출물 영상 ${s.footageUrls?.length || 0}편을 방향 ${concepts}가지 훅·자막·CTA·엔드카드로 감싸고${(s.footageUrls?.length || 0) >= 2 ? ' 몽타주 1편을 더해' : ''} 광고로 만들어요 · 이미지는 그 영상의 장면으로(생성 비용 0)`);
     else
         lines.push('이미지 생성 없이 브랜드 색 배경 + 문구로 만들어요(비용 0)');
     if (conceptsWithVideo)

package/dist/core/creatives/videofx.d.ts

@@ -86,3 +86,8 @@ export declare function refCanvas(ref: string, bgPng: string, output: string, di
 export declare function motionScore(video: string): Promise<number>;
 /** 마지막 프레임 PNG — 다음 컷 첫 프레임(인물·장소 연속) */
 export declare function lastFrame(video: string, output: string): Promise<string>;
+/** 구간 잘라내기(재인코딩 · 몽타주용) — t0 에서 sec 초 · 원본이 짧으면 있는 만큼 */
+export declare function trimClip(input: string, output: string, o: {
+    t0: number;
+    sec: number;
+}): Promise<void>;

package/dist/core/creatives/videofx.js

@@ -239,3 +239,9 @@ export async function lastFrame(video, output) {
     await execFileP('ffmpeg', ['-y', '-v', 'error', '-sseof', '-0.15', '-i', video, '-frames:v', '1', '-update', '1', output]);
     return output;
 }
+/** 구간 잘라내기(재인코딩 · 몽타주용) — t0 에서 sec 초 · 원본이 짧으면 있는 만큼 */
+export async function trimClip(input, output, o) {
+    const p = await probe(input);
+    const t0 = Math.max(0, Math.min(o.t0, Math.max(0, p.durationSec - o.sec)));
+    await execFileP('ffmpeg', ['-y', '-v', 'error', '-ss', String(t0), '-i', input, '-t', String(Math.min(o.sec, Math.max(0.5, p.durationSec - t0))), ...(p.hasAudio ? [] : ['-f', 'lavfi', '-t', String(o.sec), '-i', 'anullsrc=r=48000:cl=stereo']), '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '20', '-c:a', 'aac', '-ar', '48000', '-ac', '2', ...(p.hasAudio ? [] : ['-shortest']), '-movflags', '+faststart', output], { maxBuffer: 8 << 20 });
+}

package/dist/core/ops.d.ts

@@ -2,7 +2,7 @@ import { connector } from '../adapters/index.js';
 import type { CheckItem, Medium, MetricRow } from '../adapters/types.js';
 import { type CreativeMode, type CreativeSpec } from './creatives/media.js';
 import { type Proposal } from './optimize.js';
-import { type Goal, type Market, type Project } from './state.js';
+import { type Goal, type Market, type Placement, type Project } from './state.js';
 export type Log = (s: string) => void;
 export declare function parseMarkets(s?: string, siteLang?: string): Market[];
 export declare function opBrief(url: string, o: {
@@ -19,7 +19,8 @@ export declare function opBrief(url: string, o: {
 export declare function opCreatives(p: Project, o: {
     count?: number;
     feedback?: string;
-    images?: string;
+    images?: string; /** 실제 산출물 영상 폴더(mp4·mov·webm) → source=product · 생성 없이 훅·자막·CTA·엔드카드·몽타주 */
+    videos?: string;
     noImages?: boolean;
     force?: boolean;
     mode?: CreativeMode;
@@ -46,6 +47,7 @@ export declare function opBuild(p: Project, o?: {
     warnings: string[];
     errors: string[];
 }>;
+export declare function mergePlacements(a: Placement[], b: Placement[]): Placement[];
 export declare function opPreview(p: Project, o?: {
     log?: Log;
 }): Promise<{

package/dist/core/ops.js

@@ -6,7 +6,8 @@ import { buildBrief, explainBrief } from './brief.js';
 import { generateConcepts, validateConcepts } from './creatives/copy.js';
 import { generateBackgrounds, userBackgrounds } from './creatives/images.js';
 import { chargeFor, resolveCreativePlan } from './creatives/media.js';
-import { produceConceptVideos } from './creatives/factory.js';
+import { produceConceptVideos, produceFootageVideos } from './creatives/factory.js';
+import { thumbnail } from './creatives/videofx.js';
 import { downloadSiteImages, screenshotSite } from './creatives/siteshots.js';
 import { filterProductRefs } from './creatives/qa.js';
 import { renderConcept, renderLogo } from './creatives/render.js';
@@ -55,7 +56,10 @@ export async function opCreatives(p, o) {
     if (p.brief.specialCategory)
         throw new Error(`「${p.brief.specialCategory}」 특별 광고 카테고리는 접수할 수 없어요.`);
     // 소재 설정(형태·출처·영상) — 명시 spec > 플래그 > 프로젝트 저장값. CLI 는 --video 없으면 이미지만(비용 예측 가능).
-    const spec = { ...(p.creative || {}), ...(o.spec || {}), ...(o.mode ? { mode: o.mode } : {}), ...(o.requirements ? { source: 'guided', prompt: o.requirements } : {}) };
+    // 실제 산출물 폴더(--videos) · 없으면 저장된 product 스펙의 파일을 재사용 · --mode/--video 로 AI 생성을 다시 요청하면 product 를 푼다
+    const stored = !o.videos && (o.spec?.source || p.creative?.source) === 'product' ? ((o.spec?.footageUrls || p.creative?.footageUrls || []).filter((f) => fs.existsSync(f))) : [];
+    const footage = o.videos ? fs.readdirSync(o.videos).filter((f) => /\.(mp4|mov|webm|m4v)$/i.test(f)).sort().map((f) => path.join(o.videos, f)) : (o.mode || o.video) ? [] : stored;
+    const spec = { ...(p.creative || {}), ...(o.spec || {}), ...(o.mode ? { mode: o.mode } : {}), ...(o.requirements ? { source: 'guided', prompt: o.requirements } : {}), ...(footage.length ? { source: 'product', footageUrls: footage } : (p.creative?.source === 'product' || o.spec?.source === 'product') ? { source: 'ai', footageUrls: undefined } : {}) };
     if (o.video === false || (o.video === undefined && !o.spec?.video && !p.creative?.video && !o.mode))
         spec.video = { ...(spec.video || {}), count: 0 };
     if (o.video && !(spec.video?.count))
@@ -101,6 +105,16 @@ export async function opCreatives(p, o) {
         let bgs;
         if (o.images && spec.source !== 'guided')
             bgs = userBackgrounds(o.images, c.key);
+        else if (footage.length) {
+            const fr = path.join(dir, `footage_frame_${ci}.jpg`);
+            try {
+                await thumbnail(footage[ci % footage.length], fr, 1.0);
+                bgs = Object.fromEntries(['1x1', '4x5', '9x16', '16x9'].map((r) => [r, fr]));
+            }
+            catch {
+                bgs = {};
+            }
+        }
         else if (o.noImages || !cplan.images.enabled)
             bgs = {};
         else {
@@ -109,6 +123,10 @@ export async function opCreatives(p, o) {
         }
         log(`합성 ${c.key} × ${SIZES.length}규격…`);
         assets.push(...(await renderConcept(dir, p.brief, c, bgs, { force: o.force || !!o.feedback, log })));
+        if (footage.length) {
+            const vids = await produceFootageVideos({ dir, brief: p.brief, concept: c, clips: footage, langs, goal: p.budget.goal, log });
+            assets.push(...vids.filter((v) => v.file));
+        }
         if (cplan.videos.perConcept.length && ci < cplan.videos.conceptsWithVideo) {
             const vids = await produceConceptVideos({ dir, brief: p.brief, concept: c, jobs: cplan.videos.perConcept, backgrounds: bgs, refs: refs.length ? refs : siteImages, siteShot, siteImages, langs, tone: cplan.tone, goal: p.budget.goal, log, onAsset: (a) => { costKrw += a.costKrw; } });
             assets.push(...vids.filter((v) => v.file));
@@ -164,7 +182,7 @@ export async function opBuild(p, o = {}) {
                 saveProject(p);
                 log(`  google 전환 액션 ${ca.gtagId}/${ca.label}`);
             }
-            const r = await c.build({ slug: p.slug, brief: p.brief, concepts, assets: p.assets, goal: p.budget.goal, markets: plan.markets, dailyBudgetMinor: pm.dailyBudgetMinor, currency: pm.currency, endDate: plan.endDate, landingUrl: p.url, utmCampaign: `adpilot_${p.slug}`, pixelId: p.tracking?.pixelId, conversionActionRn, existing: p.placements, validateOnly: o.validate, log });
+            const r = await c.build({ slug: p.slug, brief: p.brief, concepts, assets: p.assets, goal: p.budget.goal, markets: plan.markets, dailyBudgetMinor: pm.dailyBudgetMinor, currency: pm.currency, endDate: plan.endDate, landingUrl: p.url, utmCampaign: `adpilot_${p.slug}`, pixelId: p.tracking?.pixelId, conversionActionRn, existing: p.placements, validateOnly: o.validate, audience: p.brief.audienceProfile ? { ageRange: p.brief.audienceProfile.ageRange, gender: p.brief.audienceProfile.gender } : undefined, strictAudience: p.creative?.audience === 'strict', log });
             warnings.push(...r.warnings);
             if (!o.validate) {
                 p.placements = mergePlacements(p.placements, r.placements);
@@ -186,8 +204,10 @@ export async function opBuild(p, o = {}) {
     }
     return { project: p, warnings, errors };
 }
-function mergePlacements(a, b) { const m = new Map(a.map((x) => [`${x.medium}/${x.kind}/${x.concept || ''}`, x])); for (const x of b)
-    m.set(`${x.medium}/${x.kind}/${x.concept || ''}`, x); return [...m.values()]; }
+// 키에 format·lang 포함 — 같은 컨셉의 이미지/영상·언어별 광고세트가 서로 덮이지 않게(웹 pipeline 과 같은 키 · 2026-09-23)
+const placementKey = (x) => `${x.medium}/${x.kind}/${x.concept || ''}/${x.format || 'image'}/${x.lang || ''}`;
+export function mergePlacements(a, b) { const m = new Map(a.map((x) => [placementKey(x), x])); for (const x of b)
+    m.set(placementKey(x), x); return [...m.values()]; }
 export async function opPreview(p, o = {}) {
     const items = [];
     for (const m of [...new Set(p.placements.map((x) => x.medium))]) {

package/dist/core/optimize.d.ts

@@ -5,23 +5,69 @@ export type Proposal = {
     kind: 'pause_ad' | 'budget_up' | 'budget_down' | 'note';
     target?: string;
     concept?: string;
+    group?: string;
     reason: string;
     newDailyMinor?: number;
 };
+export type OptimizeOpts = {
+    /** 이미 꺼진 광고(반복해서 끄지 않게 · 비교에서도 제외) */
+    excludeIds?: string[];
+    /** 마지막 예산 변경 시각 — 쿨다운(기본 24시간) 안이면 예산 제안을 내지 않는다 */
+    lastBudgetChangeAt?: string;
+    cooldownHours?: number;
+    /** 매체 최소 일 예산(최소 단위) — budget_down 이 이 아래로 내려가지 않는다 */
+    floorMinor?: number;
+    /** 비교 묶음 키(기본 lang · 없으면 전체) */
+    groupBy?: 'lang' | 'adset' | 'none';
+};
+export declare const LEARNING_HOURS = 48;
+export declare const MIN_IMPRESSIONS = 2000;
+export declare const PAUSE_RATIO = 1.8;
+export declare const BUDGET_COOLDOWN_HOURS = 24;
+/** 영상 보호 — 훅률·완주율이 이 이상이면 클릭률만으로 끄지 않는다 */
+export declare const VIDEO_KEEP: {
+    hookRate: number;
+    completion: number;
+};
 export declare function summarize(rows: MetricRow[]): {
     days: number;
     ctr: number;
     cpc: number;
     cpa: number;
+    hookRate: number;
+    completion: number;
     id: string;
     name: string;
     concept?: string;
+    format?: "image" | "video";
+    lang?: string;
+    adsetId?: string;
     spend: number;
     impressions: number;
     clicks: number;
     conversions: number;
+    videoPlays: number;
+    thruplays: number;
     currency: string;
 }[];
-export declare function proposeFor(medium: 'meta' | 'google', rows: MetricRow[], plan: Plan, launchedAt?: string): Proposal[];
+export type AdSummary = ReturnType<typeof summarize>[number];
+export declare function proposeFor(medium: 'meta' | 'google', rows: MetricRow[], plan: Plan, launchedAt?: string, opts?: OptimizeOpts): Proposal[];
 /** 예산 재배분이 월 상한을 넘지 않는지 — 매체별 새 일 예산(원 환산) 합 ≤ 계획 일 예산 */
 export declare function withinCap(plan: Plan, newDailyKrwByMedium: Record<string, number>): boolean;
+/** 승자·패자 — 새로고침(승자 유지 · 패자만 교체)에 넘길 컨셉 키. 노출 기준을 넘은 광고만 · 컨셉 단위로 합산 */
+export declare function winnersAndLosers(rows: MetricRow[], o?: {
+    minImpressions?: number;
+    top?: number;
+}): {
+    winners: string[];
+    losers: string[];
+    table: {
+        concept: string;
+        impressions: number;
+        clicks: number;
+        ctr: number;
+        conversions: number;
+        hookRate: number;
+        completion: number;
+    }[];
+};

package/dist/core/optimize.js

@@ -1,52 +1,94 @@
+export const LEARNING_HOURS = 48;
+export const MIN_IMPRESSIONS = 2000;
+export const PAUSE_RATIO = 1.8;
+export const BUDGET_COOLDOWN_HOURS = 24;
+/** 영상 보호 — 훅률·완주율이 이 이상이면 클릭률만으로 끄지 않는다 */
+export const VIDEO_KEEP = { hookRate: 0.25, completion: 0.35 };
 export function summarize(rows) {
     const by = new Map();
     for (const r of rows) {
         const k = r.id;
-        const s = by.get(k) || { id: r.id, name: r.name, concept: r.concept, spend: 0, impressions: 0, clicks: 0, conversions: 0, currency: r.currency, days: new Set() };
+        const s = by.get(k) || { id: r.id, name: r.name, concept: r.concept, format: r.format, lang: r.lang, adsetId: r.adsetId, spend: 0, impressions: 0, clicks: 0, conversions: 0, videoPlays: 0, thruplays: 0, currency: r.currency, days: new Set() };
         s.spend += r.spend;
         s.impressions += r.impressions;
         s.clicks += r.clicks;
         s.conversions += r.conversions;
+        s.videoPlays += r.videoPlays || 0;
+        s.thruplays += r.thruplays || 0;
         if (r.date)
             s.days.add(r.date);
         by.set(k, s);
     }
-    return [...by.values()].map((s) => ({ ...s, days: s.days.size, ctr: s.impressions ? s.clicks / s.impressions : 0, cpc: s.clicks ? s.spend / s.clicks : 0, cpa: s.conversions ? s.spend / s.conversions : 0 }));
+    return [...by.values()].map((s) => ({ ...s, days: s.days.size, ctr: s.impressions ? s.clicks / s.impressions : 0, cpc: s.clicks ? s.spend / s.clicks : 0, cpa: s.conversions ? s.spend / s.conversions : 0, hookRate: s.impressions ? s.videoPlays / s.impressions : 0, completion: s.videoPlays ? s.thruplays / s.videoPlays : 0 }));
 }
-export function proposeFor(medium, rows, plan, launchedAt) {
-    const ads = summarize(rows);
+const pct = (n) => `${(n * 100).toFixed(n < 0.1 ? 2 : 1)}%`;
+export function proposeFor(medium, rows, plan, launchedAt, opts = {}) {
+    const excluded = new Set(opts.excludeIds || []);
+    const ads = summarize(rows).filter((a) => !excluded.has(a.id));
     const out = [];
     const hours = launchedAt ? (Date.now() - new Date(launchedAt).getTime()) / 3600_000 : 0;
     const pm = plan.media.find((m) => m.medium === medium);
     if (!ads.length)
         return [{ medium, kind: 'note', reason: '아직 지표가 없어요(검수 중이거나 노출 전).' }];
-    if (hours < 48)
-        return [{ medium, kind: 'note', reason: `광고 시작 ${Math.floor(hours)}시간 뒤 — 학습 단계(48시간)라 소재를 건드리지 않아요.` }];
-    const eligible = ads.filter((a) => a.impressions >= 2000);
-    if (eligible.length < 2)
-        return [{ medium, kind: 'note', reason: '노출 2,000 이상인 소재가 2개 미만 — 비교하기엔 일러요.' }];
-    const useCpa = eligible.filter((a) => a.conversions > 0).length >= 2 && eligible.reduce((n, a) => n + a.conversions, 0) >= 20;
-    const score = (a) => (useCpa ? (a.conversions ? -a.cpa : -Infinity) : a.ctr);
-    const sorted = [...eligible].sort((a, b) => score(b) - score(a));
-    const best = sorted[0];
-    const worst = sorted[sorted.length - 1];
-    const ratio = useCpa ? (best.cpa && worst.cpa ? worst.cpa / best.cpa : 1) : best.ctr && worst.ctr ? best.ctr / worst.ctr : 1;
-    if (sorted.length >= 2 && ratio >= 1.8)
-        out.push({ medium, kind: 'pause_ad', target: worst.id, concept: worst.concept, reason: useCpa ? `「${worst.concept || worst.name}」 전환 단가가 1등의 ${ratio.toFixed(1)}배 — 끄고 예산을 잘 되는 쪽에 몰아요` : `「${worst.concept || worst.name}」 클릭률 ${(worst.ctr * 100).toFixed(2)}%가 1등(${(best.ctr * 100).toFixed(2)}%)의 1/${ratio.toFixed(1)} — 끄고 예산을 잘 되는 쪽에 몰아요` });
-    // 예산: 전체 평균 CTR이 1% 이상이고 예산 소진율이 높으면 +20% (상한 안에서), 소진율 낮으면 유지
+    if (hours < LEARNING_HOURS)
+        return [{ medium, kind: 'note', reason: `광고 시작 ${Math.floor(hours)}시간 뒤 — 학습 단계(${LEARNING_HOURS}시간)라 소재를 건드리지 않아요.` }];
+    // 비교 묶음 — 언어 그룹(광고세트 묶음). 묶음이 하나면 전체 비교와 같다.
+    const groupKey = (a) => (opts.groupBy === 'none' ? '' : opts.groupBy === 'adset' ? a.adsetId || '' : a.lang || '');
+    const groups = new Map();
+    for (const a of ads)
+        groups.set(groupKey(a), [...(groups.get(groupKey(a)) || []), a]);
+    let anyEligible = false;
+    let bestOverall;
+    for (const [g, list] of groups) {
+        const gl = g ? `[${g}] ` : '';
+        const eligible = list.filter((a) => a.impressions >= MIN_IMPRESSIONS);
+        if (eligible.length < 2) {
+            out.push({ medium, kind: 'note', group: g || undefined, reason: `${gl}노출 ${MIN_IMPRESSIONS.toLocaleString()} 이상인 소재가 2개 미만 — 비교하기엔 일러요.` });
+            continue;
+        }
+        anyEligible = true;
+        const useCpa = eligible.filter((a) => a.conversions > 0).length >= 2 && eligible.reduce((n, a) => n + a.conversions, 0) >= 20;
+        const score = (a) => (useCpa ? (a.conversions ? -a.cpa : -Infinity) : a.ctr);
+        const sorted = [...eligible].sort((a, b) => score(b) - score(a));
+        const best = sorted[0];
+        const worst = sorted[sorted.length - 1];
+        if (!bestOverall || score(best) > score(bestOverall))
+            bestOverall = best;
+        const ratio = useCpa ? (best.cpa && worst.cpa ? worst.cpa / best.cpa : 1) : best.ctr && worst.ctr ? best.ctr / worst.ctr : 1;
+        const vid = worst.format === 'video' && worst.videoPlays > 0 ? ` · 3초 시청 ${pct(worst.hookRate)} · 완주 ${pct(worst.completion)}` : '';
+        if (ratio >= PAUSE_RATIO) {
+            // 영상 보호 — 훅률·완주율이 좋은 영상은 인지 단계 소재로 남긴다(클릭률만으로 끄지 않음)
+            if (worst.format === 'video' && worst.videoPlays > 0 && worst.hookRate >= VIDEO_KEEP.hookRate && worst.completion >= VIDEO_KEEP.completion)
+                out.push({ medium, kind: 'note', group: g || undefined, concept: worst.concept, reason: `${gl}「${worst.concept || worst.name}」 클릭률은 1등의 1/${ratio.toFixed(1)}이지만 3초 시청 ${pct(worst.hookRate)} · 완주 ${pct(worst.completion)}로 잘 보고 있어요 — 끄지 않고 둡니다` });
+            else
+                out.push({ medium, kind: 'pause_ad', target: worst.id, concept: worst.concept, group: g || undefined, reason: useCpa ? `${gl}「${worst.concept || worst.name}」 전환 단가가 1등의 ${ratio.toFixed(1)}배 — 끄고 예산을 잘 되는 쪽에 몰아요` : `${gl}「${worst.concept || worst.name}」 클릭률 ${pct(worst.ctr)}가 1등(「${best.concept || best.name}」 ${pct(best.ctr)})의 1/${ratio.toFixed(1)}${vid} — 끄고 예산을 잘 되는 쪽에 몰아요` });
+        }
+    }
+    // 예산: 전체 평균 CTR이 1% 이상이고 예산 소진율이 높으면 +20% (상한 안에서) · 소진율 낮으면 -20%(최소 예산 위에서) · 24시간 쿨다운
     if (pm) {
+        const sinceChange = opts.lastBudgetChangeAt ? (Date.now() - new Date(opts.lastBudgetChangeAt).getTime()) / 3600_000 : Infinity;
+        const cooldown = opts.cooldownHours ?? BUDGET_COOLDOWN_HOURS;
         const days = Math.max(1, ...ads.map((a) => a.days));
         const spendPerDay = ads.reduce((n, a) => n + a.spend, 0) / days;
         const planMajor = pm.dailyBudgetMinor / (pm.currency === 'KRW' || pm.currency === 'JPY' ? 1 : 100);
         const pacing = planMajor ? spendPerDay / planMajor : 0;
-        const avgCtr = eligible.reduce((n, a) => n + a.clicks, 0) / Math.max(1, eligible.reduce((n, a) => n + a.impressions, 0));
-        if (pacing > 0.9 && avgCtr >= 0.01)
-            out.push({ medium, kind: 'budget_up', reason: `예산을 ${Math.round(pacing * 100)}% 소진하고 클릭률 ${(avgCtr * 100).toFixed(2)}% — 이 매체에 +20% 제안(월 상한 안에서 다른 매체에서 옮김)`, newDailyMinor: Math.floor(pm.dailyBudgetMinor * 1.2) });
-        else if (pacing < 0.4)
-            out.push({ medium, kind: 'budget_down', reason: `예산의 ${Math.round(pacing * 100)}%만 쓰고 있어요 — 노출 경쟁이 약하거나 타겟이 좁아요. -20% 후 다른 매체로`, newDailyMinor: Math.floor(pm.dailyBudgetMinor * 0.8) });
+        const eligibleAll = ads.filter((a) => a.impressions >= MIN_IMPRESSIONS);
+        const avgCtr = eligibleAll.reduce((n, a) => n + a.clicks, 0) / Math.max(1, eligibleAll.reduce((n, a) => n + a.impressions, 0));
+        if (sinceChange < cooldown)
+            out.push({ medium, kind: 'note', reason: `예산은 ${Math.floor(sinceChange)}시간 전에 바꿨어요 — ${cooldown}시간 지나고 다시 봐요(소진율 ${Math.round(pacing * 100)}%)` });
+        else if (pacing > 0.9 && avgCtr >= 0.01)
+            out.push({ medium, kind: 'budget_up', reason: `예산을 ${Math.round(pacing * 100)}% 소진하고 클릭률 ${pct(avgCtr)} — 이 매체에 +20% 제안(월 상한 안에서)`, newDailyMinor: Math.floor(pm.dailyBudgetMinor * 1.2) });
+        else if (pacing < 0.4) {
+            const floor = opts.floorMinor || 0;
+            const next = Math.max(floor, Math.floor(pm.dailyBudgetMinor * 0.8));
+            if (next < pm.dailyBudgetMinor)
+                out.push({ medium, kind: 'budget_down', reason: `예산의 ${Math.round(pacing * 100)}%만 쓰고 있어요 — 노출 경쟁이 약하거나 타겟이 좁아요. -20%${next === floor ? '(매체 최소 예산까지)' : ''}`, newDailyMinor: next });
+            else
+                out.push({ medium, kind: 'note', reason: `예산의 ${Math.round(pacing * 100)}%만 쓰지만 이미 매체 최소 예산이에요 — 그대로 둡니다` });
+        }
     }
-    if (!out.length)
-        out.push({ medium, kind: 'note', reason: `소재 간 차이가 크지 않아 그대로 둡니다 (1등 「${best.concept || best.name}」).` });
+    if (!out.some((o) => o.kind !== 'note') && anyEligible && bestOverall)
+        out.push({ medium, kind: 'note', reason: `소재 간 차이가 크지 않아 그대로 둡니다 (1등 「${bestOverall.concept || bestOverall.name}」).` });
     return out;
 }
 /** 예산 재배분이 월 상한을 넘지 않는지 — 매체별 새 일 예산(원 환산) 합 ≤ 계획 일 예산 */
@@ -54,3 +96,25 @@ export function withinCap(plan, newDailyKrwByMedium) {
     const total = plan.media.reduce((n, m) => n + (newDailyKrwByMedium[m.medium] ?? m.dailyBudgetKrw), 0);
     return total <= plan.dailyKrw * 1.02 + 2000;
 }
+/** 승자·패자 — 새로고침(승자 유지 · 패자만 교체)에 넘길 컨셉 키. 노출 기준을 넘은 광고만 · 컨셉 단위로 합산 */
+export function winnersAndLosers(rows, o = {}) {
+    const byConcept = new Map();
+    for (const r of rows) {
+        const k = (r.concept || '').replace(/\(영상\)$/, '');
+        if (!k)
+            continue;
+        const s = byConcept.get(k) || { concept: k, impressions: 0, clicks: 0, conversions: 0, videoPlays: 0, thruplays: 0 };
+        s.impressions += r.impressions;
+        s.clicks += r.clicks;
+        s.conversions += r.conversions;
+        s.videoPlays += r.videoPlays || 0;
+        s.thruplays += r.thruplays || 0;
+        byConcept.set(k, s);
+    }
+    const table = [...byConcept.values()].map((s) => ({ concept: s.concept, impressions: s.impressions, clicks: s.clicks, conversions: s.conversions, ctr: s.impressions ? s.clicks / s.impressions : 0, hookRate: s.impressions ? s.videoPlays / s.impressions : 0, completion: s.videoPlays ? s.thruplays / s.videoPlays : 0 })).sort((a, b) => b.ctr - a.ctr);
+    const eligible = table.filter((t) => t.impressions >= (o.minImpressions ?? MIN_IMPRESSIONS));
+    const top = o.top ?? 2;
+    const winners = eligible.slice(0, top).map((t) => t.concept);
+    const losers = eligible.length > top ? [eligible[eligible.length - 1].concept] : [];
+    return { winners, losers, table };
+}

package/dist/core/state.d.ts

@@ -142,7 +142,8 @@ export type Placement = {
     externalId: string;
     name: string;
     status: string;
-    createdAt: string;
+    createdAt: string; /** 규칙이 끈 광고 — 「광고 시작」이 다시 켜지 않는다 */
+    pausedBy?: 'rule' | 'user';
 };
 export type ProjectStatus = 'draft' | 'briefed' | 'creatives' | 'planned' | 'built' | 'live' | 'paused' | 'ended';
 export type Project = {

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export * from './core/report.js';
 export * from './core/tracking.js';
 export * from './core/check.js';
 export * from './adapters/types.js';
+export * from './adapters/meta-targeting.js';
 export { MetaConnector } from './adapters/meta.js';
 export { GoogleConnector, GEO, LANG } from './adapters/google.js';
 export { MockConnector } from './adapters/mock.js';

package/dist/index.js

@@ -25,6 +25,7 @@ export * from './core/report.js';
 export * from './core/tracking.js';
 export * from './core/check.js';
 export * from './adapters/types.js';
+export * from './adapters/meta-targeting.js';
 export { MetaConnector } from './adapters/meta.js';
 export { GoogleConnector, GEO, LANG } from './adapters/google.js';
 export { MockConnector } from './adapters/mock.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adyou",
-  "version": "0.6.18",
+  "version": "0.7.1",
   "description": "ADYou — 대행사 없이, 당신이 직접. 사이트 주소 하나로 광고 소재·매체 등록·자동 운영·보고까지: AI 광고 자율주행 CLI + MCP 서버(Meta·Google · 생성은 항상 PAUSED · 승인 뒤 시작)",
   "type": "module",
   "license": "MIT",