@mj-biz-apps/marketing-server 0.3.0 → 0.4.0

package/dist/programs/linkedin/LinkedInAdsProgramDriver.js

@@ -39,7 +39,8 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 import { LogError, LogStatus, Metadata, RunView } from '@memberjunction/core';
 import { EscapeSQLString, RegisterClass } from '@memberjunction/global';
 import { ConvergeObservation } from '@mj-biz-apps/marketing-actions';
-import { BaseProgramTypeDriver, LINKEDIN_ADS_TYPE_NAME, parseAdCampaignConfig, platformObjectName, stampUtm, toMarketingEntityName, assertPublicHttpUrl, effectiveCreative, elapsedReportingRange, } from '@mj-biz-apps/marketing-core';
+import { BaseProgramTypeDriver, LINKEDIN_ADS_TYPE_NAME, parseAdCampaignConfig, platformObjectName, stampUtm, toMarketingEntityName, assertPublicHttpUrl, effectiveCreative, AUDIENCE_MAX_MEMBERS, MATCHED_AUDIENCE_MIN_MEMBERS, INTRO_TEXT_UNCLIPPED_LENGTH, elapsedReportingRange, containerRunSchedule, platformRunSchedule } from '@mj-biz-apps/marketing-core';
+import { CONVERSION_SCOPE, lacksConversionScope } from './LinkedInAdsClient.js';
 import { isLinkedInRefused, resolveLinkedInExecutionContext, LINKEDIN_CREDENTIAL_TYPE } from './linkedInExecutionContext.js';
 const REFS_ENTITY = 'MJ_BizApps_Marketing: Program Platform Refs';
 let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgramTypeDriver {
@@ -50,13 +51,15 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
         this.typeName = LINKEDIN_ADS_TYPE_NAME;
         /** Mirrors AdCampaignConfig — the parser is the enforcement, this is the declaration. */
         this.paramSpecs = [
-            { name: 'tacticConfigJSON', valueType: 'Scalar', isArray: false, isRequired: true, description: 'The levers as JSON (Program.TacticConfigJSON): audience (targeted | website-retargeting | lookalike), dailyBudgetUsd, landingPageUrl, optional creativeHeadline/creativeBody/audienceWindowDays.' },
+            { name: 'tacticConfigJSON', valueType: 'Scalar', isArray: false, isRequired: true, description: 'The levers as JSON (Program.TacticConfigJSON): audience (targeted | website-retargeting), dailyBudgetUsd, landingPageUrl, optional creativeHeadline/creativeBody/audienceWindowDays.' },
             { name: 'campaignCode', valueType: 'Scalar', isArray: false, isRequired: true, description: 'Program.Code — stamped as utm_campaign and prefixed onto every platform object name.' },
         ];
     }
     async validateProposal(program) {
         const parsed = parseAdCampaignConfig(this.rawConfig(program));
         const issues = [...parsed.issues];
+        if (parsed.config)
+            issues.push(...validateLinkedInCreative(parsed.config));
         const user = this.contextUser;
         if (user) {
             const ctx = await this.resolveContext(program.brandId, user);
@@ -69,6 +72,89 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
                     message: `${i.message} Lock will refuse until this is resolved.`,
                 })));
             }
+            else if (parsed.config) {
+                issues.push(...await this.validateAudienceAndConversion(parsed.config, ctx));
+            }
+        }
+        return issues;
+    }
+    /**
+     * The audience and the conversion are platform OBJECTS the levers point at by id (R1/R2/R5, D-34): the pre-check
+     * looks them up so an id the account does not hold, a country-wide audience or an audience LinkedIn will not serve
+     * to is refused while the proposal is still a draft — not discovered at lock, and never, as with CP-02, discovered
+     * on the invoice. One GET each; a lookup that fails is a warning (the platform, not the proposal, is the problem).
+     */
+    async validateAudienceAndConversion(config, ctx) {
+        const issues = [];
+        const templateId = config.audienceTemplateId ?? ctx.defaultAudienceTemplateId;
+        if (config.audience === 'targeted' && !templateId) {
+            issues.push({
+                severity: 'error', code: 'LI_AUDIENCE_LOCATION_ONLY',
+                message: 'A targeted LinkedIn program needs a saved audience: set one in the levers (audienceTemplateId) or set the connection\'s default saved audience in Settings → Connections. A location alone is not an audience — it is everyone in it.',
+            });
+        }
+        else if (templateId) {
+            try {
+                const template = await ctx.client.findAudienceTemplateById(templateId);
+                if (!template) {
+                    const have = (await ctx.client.audienceTemplates()).map(t => `${t.id} "${t.name}"`).slice(0, 12).join(', ');
+                    issues.push({
+                        severity: 'error', code: 'LI_AUDIENCE_TEMPLATE_UNKNOWN',
+                        message: `No saved audience with id ${templateId}${config.audienceTemplateId ? '' : ' (the connection\'s default)'} on ad account ${ctx.adAccountId}. The account has: ${have || 'none'}.`,
+                    });
+                }
+                else {
+                    issues.push(...audienceSizeIssues(template));
+                }
+            }
+            catch (e) {
+                issues.push({ severity: 'warning', code: 'LI_AUDIENCE_LOOKUP_FAILED', message: `Could not read the account's saved audiences: ${e instanceof Error ? e.message : String(e)}. Lock will look again.` });
+            }
+        }
+        if (config.conversionId) {
+            try {
+                // KI-148: attaching a conversion is an UPDATE on it and needs the Conversions API scope; CP-02 found this
+                // at lock, after the campaign existed. Refuse here, while the proposal is a draft.
+                if (lacksConversionScope(await ctx.client.tokenScopes())) {
+                    issues.push({ severity: 'error', code: 'LI_CONVERSION_SCOPE', message: conversionScopeMessage() });
+                    return issues;
+                }
+                const conversion = await ctx.client.findConversionById(config.conversionId);
+                if (!conversion) {
+                    const have = (await ctx.client.conversions()).map(c => `${c.id} "${c.name}"`).slice(0, 12).join(', ');
+                    issues.push({
+                        severity: 'error', code: 'LI_CONVERSION_UNKNOWN',
+                        message: `No conversion with id ${config.conversionId} on ad account ${ctx.adAccountId}. The account has: ${have || 'none'}.`,
+                    });
+                }
+                else if (!conversion.enabled) {
+                    issues.push({ severity: 'warning', code: 'LI_CONVERSION_DISABLED', message: `Conversion "${conversion.name}" is disabled in Campaign Manager — the campaign will optimise for it but it will not count until it is enabled.` });
+                }
+            }
+            catch (e) {
+                issues.push({ severity: 'warning', code: 'LI_CONVERSION_LOOKUP_FAILED', message: `Could not read the account's conversions: ${e instanceof Error ? e.message : String(e)}. Lock will look again.` });
+            }
+        }
+        else if (config.optimizeFor === 'clicks') {
+            issues.push({
+                severity: 'notice', code: 'LI_OPTIMISES_FOR_CLICKS',
+                message: 'No conversion — the campaign optimises for landing-page clicks and the program is measured by them (D-31). The metric must be a click count; a download, sign-up or form fill needs a conversion in Campaign Manager, set by its id in the levers (conversionId).',
+            });
+        }
+        else {
+            // D-31: neither a conversion nor an explicit "clicks" — the program would be measured by a number LinkedIn
+            // cannot report (the AAiP draft promised sign-ups; externalWebsiteConversions would have stayed 0 → Kill).
+            let names = '';
+            try {
+                names = (await ctx.client.conversions()).map(c => `"${c.name}"`).slice(0, 12).join(', ');
+            }
+            catch { /* the list is a courtesy */ }
+            issues.push({
+                severity: 'error', code: 'LI_NO_CONVERSION',
+                message: 'Choose what the program is measured by: name a conversion from the ad account in the levers (conversion) so LinkedIn optimises for it, '
+                    + 'or set optimizeFor: "clicks" and make the metric a landing-page click count. '
+                    + `Ad account ${ctx.adAccountId} has: ${names || 'no conversions yet — create one in Campaign Manager, or optimise for clicks'}.`,
+            });
         }
         return issues;
     }
@@ -92,6 +178,36 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
         // a step existed (CP-02 predates the ad step) — is finished on the next run, not skipped.
         const existing = await this.loadRefs(program.id, user);
         const stampedUrl = stampUtm(config.landingPageUrl, code, 'linkedin');
+        // The audience (R1): the levers' saved audience, else the connection's default, by id (D-34); a targeted
+        // program with neither is refused here too (the pre-check said so at propose; this is the door spend walks
+        // through).
+        const templateId = config.audienceTemplateId ?? ctx.defaultAudienceTemplateId;
+        let template = null;
+        if (templateId) {
+            template = await ctx.client.findAudienceTemplateById(templateId);
+            if (!template)
+                throw new Error(`LinkedIn Ads launch refused: no saved audience with id ${templateId} on ad account ${ctx.adAccountId}.`);
+            const tooBig = audienceSizeIssues(template).find(i => i.severity === 'error');
+            if (tooBig)
+                throw new Error(`LinkedIn Ads launch refused: ${tooBig.message}`);
+        }
+        else if (config.audience === 'targeted') {
+            throw new Error('LinkedIn Ads launch refused: a targeted program needs a saved audience (audienceTemplateId lever, or the connection\'s default in Settings → Connections) — a location alone is everyone in it.');
+        }
+        // The conversion (R5): set by id → the campaign optimises for it and it is attached below.
+        let conversion = null;
+        if (config.conversionId) {
+            // Before anything is created on LinkedIn (KI-148): the association would fail last, leaving a group and a campaign behind.
+            if (lacksConversionScope(await ctx.client.tokenScopes()))
+                throw new Error(`LinkedIn Ads launch refused: ${conversionScopeMessage()}`);
+            conversion = await ctx.client.findConversionById(config.conversionId);
+            if (!conversion)
+                throw new Error(`LinkedIn Ads launch refused: no conversion with id ${config.conversionId} on ad account ${ctx.adAccountId}.`);
+        }
+        if (!conversion && config.optimizeFor !== 'clicks') {
+            throw new Error('LinkedIn Ads launch refused: the levers name no conversion and do not choose optimizeFor: "clicks" — the program has nothing to be measured by (D-31).');
+        }
+        const objective = conversion ? 'WEBSITE_CONVERSION' : 'WEBSITE_VISIT';
         let audienceUrn = null;
         if (config.audience === 'website-retargeting') {
             const days = config.audienceWindowDays ?? 90;
@@ -112,8 +228,10 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
             }
         }
         const runSchedule = await this.runScheduleFor(program, user);
+        // KI-143: the group is a container whose start LinkedIn freezes once it is not a draft — it starts at lock
+        // time so a sprint pulled forward later (KI-119's hook) still falls inside it. The campaign gets the window.
         const groupUrn = existing.find(r => r.ExternalKind === 'CampaignGroup')?.ExternalURN
-            ?? await ctx.client.createCampaignGroup(platformObjectName(code, 'campaign-group'), runSchedule);
+            ?? await ctx.client.createCampaignGroup(platformObjectName(code, 'campaign-group'), containerRunSchedule(runSchedule));
         await this.saveRef(program.id, ctx.brandConnectionId, 'CampaignGroup', groupUrn, null, user);
         // The connection decides whether lock means "running" or "ready": PAUSED by default,
         // so a real account never starts spending because someone scheduled a sprint.
@@ -124,6 +242,8 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
             name: platformObjectName(code, 'campaign'),
             dailyBudgetUsd: config.dailyBudgetUsd,
             audienceUrn,
+            targetingCriteria: template?.targetingCriteria ?? {},
+            objective,
             status: campaignStatus,
             runSchedule,
             organizationUrn,
@@ -133,68 +253,102 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
                 dailyBudgetUsd: config.dailyBudgetUsd,
                 landingPageUrl: stampedUrl,
                 audience: config.audience,
+                audienceTemplate: template ? { id: template.id, name: template.name, approximateMemberCount: template.approximateMemberCount } : null,
+                objective,
+                conversion: conversion ? { id: conversion.id, name: conversion.name } : null,
+                // D-31: what collectMetrics reads back as the program's number — frozen with the campaign, like the levers.
+                optimizeFor: conversion ? 'conversions' : 'clicks',
                 status: campaignStatus,
             }, user);
         }
-        const adNote = await this.attachCreative(program, ctx, code, config, campaignUrn, organizationUrn, stampedUrl, campaignStatus, existing, user);
-        LogStatus(`LinkedInAdsProgramDriver.onLock: ${code} ${campaignStatus === 'ACTIVE' ? 'launched' : 'created PAUSED (Settings → Connections decides when it serves)'} — ${config.audience} audience, `
-            + `$${config.dailyBudgetUsd}/day, campaign ${campaignUrn}; ${adNote}. Stamped landing URL recorded on the campaign ref.`);
+        // Idempotent per step: a lock that died between the campaign and this PUT attaches it on the next run.
+        if (conversion) {
+            await ctx.client.associateConversion(campaignUrn, conversion.urn);
+        }
+        const adNote = await this.attachCreatives(program, ctx, code, config, campaignUrn, organizationUrn, stampedUrl, campaignStatus, existing, user);
+        LogStatus(`LinkedInAdsProgramDriver.onLock: ${code} ${campaignStatus === 'ACTIVE' ? 'launched' : 'created PAUSED (Settings → Connections decides when it serves)'} — ${config.audience} audience`
+            + (template ? ` "${template.name}" (~${template.approximateMemberCount ?? '?'} members)` : '') + `, `
+            + `$${config.dailyBudgetUsd}/day, ${objective}${conversion ? ` optimising for "${conversion.name}"` : ''}, campaign ${campaignUrn}; ${adNote}. Stamped landing URL recorded on the campaign ref.`);
     }
     /**
-     * The ad itself: the agent's creative, posted as Direct Sponsored Content from the brand's
-     * page (a dark post — it exists only inside the campaign, never on the page's feed) and
-     * attached to the campaign as a creative. Mirrors the Google driver's contract: no headline
-     * means the campaign launches ad-less and SAYS so; a missing or unusable brand image degrades
-     * to an article ad (link card) rather than to no ad; a second lock finds the ref and skips.
+     * The ads themselves (R4): ONE creative per headline, up to five, each the agent's copy posted as Direct Sponsored
+     * Content from the brand's page (a dark post — it exists only inside the campaign, never on the page's feed) and
+     * attached to the campaign, so `creativeSelection: OPTIMIZED` has something to optimise. Mirrors the Google
+     * driver's contract: no headline means the campaign launches ad-less and SAYS so; a missing or unusable image
+     * degrades to an article ad (link card) rather than to no ad. Idempotent per VARIANT: a second lock finds each
+     * variant's ref (or adopts an orphan by name) and creates only what is missing.
      */
-    async attachCreative(program, ctx, code, config, campaignUrn, organizationUrn, stampedUrl, campaignStatus, existing, user) {
-        if (existing.some(r => r.ExternalKind === 'Creative'))
-            return 'ad already attached (idempotent)';
+    async attachCreatives(program, ctx, code, config, campaignUrn, organizationUrn, stampedUrl, campaignStatus, existing, user) {
         const creative = effectiveCreative(config);
-        const headline = creative.headlines[0];
-        if (!headline)
+        if (creative.headlines.length === 0)
             return 'no creative in the levers — campaign launches ad-less';
-        // ADOPT BEFORE CREATE: an earlier lock may have created the ad and died before recording
-        // it (the first live run did exactly that). Anything already on this campaign under our
-        // name is ours — record it and stop.
-        const adName = platformObjectName(code, 'campaign', 'ad');
-        const orphan = (await ctx.client.creativesForCampaign(campaignUrn)).find(c => c.name === adName && c.intendedStatus !== 'ARCHIVED');
-        if (orphan) {
-            await this.saveRef(program.id, ctx.brandConnectionId, 'Creative', orphan.urn, {
-                postUrn: orphan.postUrn, headline, adopted: true, campaignStatus,
-            }, user);
-            return `ad adopted from the account (${orphan.urn})`;
-        }
-        const description = creative.descriptions[0] ?? null;
-        // The intro text above the card: the long headline when the agent wrote one, else the
-        // description, else the headline again. LinkedIn caps it at 600 characters.
-        const commentary = (creative.longHeadline ?? description ?? headline).slice(0, 600);
+        const variants = creative.headlines.slice(0, 5);
+        const attached = new Set(existing.filter(r => r.ExternalKind === 'Creative').map(r => Number(this.stateOf(r)['variant'] ?? 1)));
+        if (variants.every((_, i) => attached.has(i + 1)))
+            return `${variants.length} ad(s) already attached (idempotent)`;
+        // The image once, shared by every variant: the program's own (creativeImageUrl, KI-117) first; the brand's
+        // landscape image is the DEFAULT, not the only option. An unusable program image degrades to the brand image.
         let imageUrn = null;
         let imageNote = 'article ad (no brand marketing image)';
-        try {
-            imageUrn = await this.uploadBrandImage(program.brandId, organizationUrn, ctx, user);
-            if (imageUrn)
-                imageNote = 'single-image ad with the brand marketing image';
-        }
-        catch (e) {
-            imageNote = `article ad — brand image not used (${e instanceof Error ? e.message : String(e)})`;
-            LogStatus(`LinkedInAdsProgramDriver.onLock: ${code} ${imageNote}`);
-        }
-        const creativeUrn = await ctx.client.createInlineCreative({
-            campaignUrn, organizationUrn,
-            name: adName,
-            commentary, headline, description,
-            landingPageUrl: stampedUrl,
-            imageUrn,
-            // The campaign's status governs serving; the creative itself is ready.
-            intendedStatus: 'ACTIVE',
-        });
-        const postUrn = await ctx.client.creativePostUrn(creativeUrn).catch(() => null);
-        await this.saveRef(program.id, ctx.brandConnectionId, 'Creative', creativeUrn, {
-            postUrn, imageUrn, headline, description, commentary, callToAction: 'LEARN_MORE',
-            format: imageUrn ? 'single-image' : 'article', campaignStatus,
-        }, user);
-        return `${imageNote} attached as ${creativeUrn}`;
+        if (creative.imageUrl) {
+            try {
+                imageUrn = await this.uploadImageFromUrl(creative.imageUrl, 'program creative image', organizationUrn, ctx);
+                imageNote = 'single-image ad with the program\'s own creative image';
+            }
+            catch (e) {
+                LogStatus(`LinkedInAdsProgramDriver.onLock: ${code} program creative image not used (${e instanceof Error ? e.message : String(e)}) — falling back to the brand image.`);
+            }
+        }
+        if (!imageUrn) {
+            try {
+                imageUrn = await this.uploadBrandImage(program.brandId, organizationUrn, ctx, user);
+                if (imageUrn)
+                    imageNote = creative.imageUrl ? 'single-image ad with the brand marketing image (program image unusable)' : 'single-image ad with the brand marketing image';
+            }
+            catch (e) {
+                imageNote = `article ad — brand image not used (${e instanceof Error ? e.message : String(e)})`;
+                LogStatus(`LinkedInAdsProgramDriver.onLock: ${code} ${imageNote}`);
+            }
+        }
+        const onAccount = await ctx.client.creativesForCampaign(campaignUrn);
+        const notes = [];
+        for (let i = 0; i < variants.length; i++) {
+            const variant = i + 1;
+            if (attached.has(variant))
+                continue;
+            const headline = variants[i];
+            const description = creative.descriptions[i] ?? creative.descriptions[0] ?? null;
+            const adName = platformObjectName(code, 'campaign', variants.length > 1 ? `ad ${variant}` : 'ad');
+            // ADOPT BEFORE CREATE: an earlier lock may have created this ad and died before recording it (the
+            // first live run did exactly that). Anything on this campaign under our name is ours.
+            const orphan = onAccount.find(c => c.name === adName && c.intendedStatus !== 'ARCHIVED');
+            if (orphan) {
+                await this.saveRef(program.id, ctx.brandConnectionId, 'Creative', orphan.urn, {
+                    variant, postUrn: orphan.postUrn, headline, adopted: true, campaignStatus, callToAction: creative.callToAction,
+                }, user);
+                notes.push(`ad ${variant} adopted from the account (${orphan.urn})`);
+                continue;
+            }
+            const creativeUrn = await ctx.client.createInlineCreative({
+                campaignUrn, organizationUrn,
+                name: adName,
+                commentary: creative.introText ?? headline,
+                headline, description,
+                landingPageUrl: stampedUrl,
+                imageUrn,
+                callToAction: creative.callToAction,
+                // The campaign's status governs serving; the creative itself is ready.
+                intendedStatus: 'ACTIVE',
+            });
+            const postUrn = await ctx.client.creativePostUrn(creativeUrn).catch(() => null);
+            await this.saveRef(program.id, ctx.brandConnectionId, 'Creative', creativeUrn, {
+                variant, postUrn, imageUrn, headline, description, commentary: creative.introText ?? headline,
+                introTextDerived: creative.introTextDerived, callToAction: creative.callToAction,
+                format: imageUrn ? 'single-image' : 'article', campaignStatus,
+            }, user);
+            notes.push(`ad ${variant} ${creativeUrn}`);
+        }
+        return `${imageNote}; ${variants.length} variant(s), ${creative.callToAction}: ${notes.join(', ')}`;
     }
     /**
      * The brand's marketing image (Brand.MarketingImageURL — Settings → Brand ad assets), fetched
@@ -206,19 +360,22 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
         const brand = await new Metadata().GetEntityObject('MJ_BizApps_Marketing: Brands', user);
         if (!await brand.Load(brandId) || !brand.MarketingImageURL)
             return null;
-        const url = brand.MarketingImageURL;
+        return this.uploadImageFromUrl(brand.MarketingImageURL, 'marketing image', organizationUrn, ctx);
+    }
+    /** One fetch-and-upload for every image source (brand or program): public URL only, PNG/JPEG, 5MB. */
+    async uploadImageFromUrl(url, label, organizationUrn, ctx) {
         const safety = assertPublicHttpUrl(url);
         if (!safety.ok)
-            throw new Error(`marketing image URL refused: ${safety.reason}`);
+            throw new Error(`${label} URL refused: ${safety.reason}`);
         const res = await fetch(url, { redirect: 'follow' });
         if (!res.ok)
-            throw new Error(`marketing image URL returned ${res.status}`);
+            throw new Error(`${label} URL returned ${res.status}`);
         const type = (res.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
         if (type !== 'image/png' && type !== 'image/jpeg')
-            throw new Error(`marketing image is ${type || 'unknown type'} — PNG or JPEG required`);
+            throw new Error(`${label} is ${type || 'unknown type'} — PNG or JPEG required`);
         const bytes = new Uint8Array(await res.arrayBuffer());
         if (bytes.byteLength > 5 * 1024 * 1024)
-            throw new Error('marketing image exceeds 5MB');
+            throw new Error(`${label} exceeds 5MB`);
         return ctx.client.uploadImage(organizationUrn, bytes, type);
     }
     async collectMetrics(program, window) {
@@ -226,9 +383,14 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
         if (!user || !program.id)
             return null;
         const refs = await this.loadRefs(program.id, user);
-        const campaigns = refs.filter(r => r.ExternalKind === 'Campaign').map(r => r.ExternalURN);
+        const campaignRefs = refs.filter(r => r.ExternalKind === 'Campaign');
+        const campaigns = campaignRefs.map(r => r.ExternalURN);
         if (campaigns.length === 0)
             return null;
+        // D-31: the observed metric is what the campaign was built to optimise for — the conversion when one is
+        // attached, landing-page clicks otherwise. Reading the ref, not the levers, keeps the measurement with the
+        // campaign that actually ran.
+        const measuresConversions = campaignRefs.some(r => this.stateOf(r)['conversion'] != null);
         const ctx = await this.resolveContext(program.brandId, user);
         if (isLinkedInRefused(ctx)) {
             LogStatus(`LinkedInAdsProgramDriver.collectMetrics: connection unavailable (${ctx.issues.map(i => i.code).join(', ')}) — no observation.`);
@@ -245,7 +407,8 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
         // wrote no row at all for a paused or test-account campaign (KI-34, host rehearsal).
         return [{
                 segmentLabel: null,
-                observedMetric: a.externalWebsiteConversions,
+                observedMetric: measuresConversions ? a.externalWebsiteConversions : a.landingPageClicks,
+                measures: measuresConversions ? 'conversions' : 'landing-page clicks',
                 conversionsCount: a.externalWebsiteConversions,
                 sampleSize: a.impressions,
                 source: `linkedin:adAnalytics:${ctx.adAccountId}`,
@@ -272,8 +435,8 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
         if (!top)
             return { refreshed: false, sprintsUpdated: 0, observationsWritten: 0, note: `LinkedInAdsProgramDriver: no campaign ref or the connection is unavailable — nothing to observe.` };
         const saved = await ConvergeObservation({ programId: program.id, sprintId, attribution: top.attribution ?? 'Inferred', sourceRefPrefix: 'linkedin:' }, { window, activityCount: top.sampleSize ?? 0, conversionsCount: top.conversionsCount, observedMetric: top.observedMetric, sourceRef: top.source,
-            notes: `platform-reported (Inferred): conversions ${top.conversionsCount}, impressions ${top.sampleSize ?? 0}` }, user);
-        const note = `LinkedInAdsProgramDriver: ${top.conversionsCount} platform conversion(s) over ${top.sampleSize ?? 0} impressions — ${saved ? 'observation converged' : 'observation NOT saved'}.`;
+            notes: `platform-reported (Inferred): measured ${top.observedMetric} ${top.measures ?? 'conversions'}, conversions ${top.conversionsCount}, impressions ${top.sampleSize ?? 0}` }, user);
+        const note = `LinkedInAdsProgramDriver: measured ${top.observedMetric} ${top.measures ?? 'conversions'}, ${top.conversionsCount} platform conversion(s) over ${top.sampleSize ?? 0} impressions — ${saved ? 'observation converged' : 'observation NOT saved'}.`;
         LogStatus(`LinkedInAdsProgramDriver.refreshStatus: ${note}`);
         return { refreshed: true, sprintsUpdated: 0, observationsWritten: saved ? 1 : 0, note };
     }
@@ -301,15 +464,21 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
         // is the part that costs money.
         const creatives = refs.filter(r => r.ExternalKind === 'Creative');
         let archived = 0;
+        let held = 0;
         const cleanupFailures = [];
         for (const ref of creatives) {
             try {
-                await ctx.client.setCreativeStatus(ref.ExternalURN, 'ARCHIVED');
+                // KI-146: LinkedIn archives only an APPROVED creative; one it has not approved allows no status change
+                // at all and is left held — its campaign is paused and its post deleted below, so it cannot serve.
+                const status = await ctx.client.retireCreative(ref.ExternalURN);
                 const postUrn = this.stateOf(ref)['postUrn'];
                 if (typeof postUrn === 'string' && postUrn)
                     await ctx.client.deletePost(postUrn);
-                await this.updateRefState(ref, { status: 'ARCHIVED', postDeleted: typeof postUrn === 'string', retiredFor: reason }, user);
-                archived++;
+                await this.updateRefState(ref, { status, postDeleted: typeof postUrn === 'string', retiredFor: reason }, user);
+                if (status === 'ARCHIVED')
+                    archived++;
+                else
+                    held++;
             }
             catch (e) {
                 const msg = e instanceof Error ? e.message : String(e);
@@ -320,11 +489,70 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
         // The summary counts what actually happened (KI-38: the first cut reported every creative
         // as archived even when LinkedIn refused — a REJECTED creative cannot change status).
         const note = `LinkedIn Ads: ${campaigns.length} campaign(s) paused, `
-            + `${archived} of ${creatives.length} creative(s) archived and their posts deleted (${reason})`
+            + `${archived} of ${creatives.length} creative(s) archived`
+            + (held > 0 ? ` and ${held} left held (LinkedIn allows no status change on a creative it has not approved; the paused campaign and the deleted post keep it from serving)` : '')
+            + `, posts deleted (${reason})`
             + (cleanupFailures.length > 0 ? `; ${cleanupFailures.length} creative cleanup(s) failed and remain on the account.` : '.');
         LogStatus(`LinkedInAdsProgramDriver.onRetire: ${program.name ?? program.id} — ${note}`);
         return { stoodDown: true, note };
     }
+    /** Stop serving, keep everything (R6 / KI-120): the campaigns go PAUSED; creatives and posts stay. */
+    async onPause(program) {
+        return this.setServing(program, 'PAUSED');
+    }
+    async onResume(program) {
+        return this.setServing(program, 'ACTIVE');
+    }
+    async setServing(program, status) {
+        const user = this.requireUser();
+        if (!program.id)
+            return { changed: false, note: 'LinkedIn Ads: nothing to change — the program has no id.' };
+        const refs = await this.loadRefs(program.id, user);
+        const campaigns = refs.filter(r => r.ExternalKind === 'Campaign');
+        if (campaigns.length === 0)
+            return { changed: false, note: 'LinkedIn Ads: nothing serving — no campaign was ever launched for this program.' };
+        const ctx = await this.resolveContext(program.brandId, user);
+        if (isLinkedInRefused(ctx)) {
+            throw new Error(`LinkedIn Ads could not reach the platform to set ${status}: ${ctx.issues.map(i => i.message).join(' ')}`);
+        }
+        for (const ref of campaigns) {
+            await ctx.client.setCampaignStatus(ref.ExternalURN, status);
+            await this.updateRefState(ref, { status, servingChangedAt: new Date().toISOString() }, user);
+        }
+        const note = `LinkedIn Ads: ${campaigns.length} campaign(s) ${status === 'PAUSED' ? 'paused' : 'resumed'}.`;
+        LogStatus(`LinkedInAdsProgramDriver.${status === 'PAUSED' ? 'onPause' : 'onResume'}: ${program.name ?? program.id} — ${note}`);
+        return { changed: true, note };
+    }
+    /** The account's saved audiences and conversions (R1/R5): what Settings offers and the agent may name. */
+    async listAudienceOptions(brandId) {
+        const user = this.contextUser;
+        if (!user)
+            return null;
+        const ctx = await this.resolveContext(brandId, user);
+        if (isLinkedInRefused(ctx))
+            return null;
+        const [templates, conversions] = await Promise.all([ctx.client.audienceTemplates(), ctx.client.conversions()]);
+        return {
+            audiences: templates.map(t => ({ name: t.name, approximateMemberCount: t.approximateMemberCount, id: t.id })),
+            conversions: conversions.map(c => ({ name: c.name, enabled: c.enabled, id: c.id })),
+        };
+    }
+    /** Live figures since the campaign was created (R6): what the early serving check judges. */
+    async servingSnapshot(program) {
+        const user = this.contextUser;
+        if (!user || !program.id)
+            return null;
+        const refs = await this.loadRefs(program.id, user);
+        const campaigns = refs.filter(r => r.ExternalKind === 'Campaign');
+        if (campaigns.length === 0)
+            return null;
+        const ctx = await this.resolveContext(program.brandId, user);
+        if (isLinkedInRefused(ctx))
+            return null;
+        const launchedAt = campaigns.map(r => new Date(r.__mj_CreatedAt)).sort((a, b) => a.getTime() - b.getTime())[0];
+        const a = await ctx.client.campaignAnalytics(campaigns.map(r => r.ExternalURN), launchedAt, new Date());
+        return { launchedAt, impressions: a.impressions, clicks: a.clicks, landingPageClicks: a.landingPageClicks, spendUsd: a.spendUsd };
+    }
     // ── refs (the driver's memory) ──────────────────────────────────────────
     /**
      * Which company page sponsors the campaign. The ad account's `reference` wins when it is a
@@ -375,8 +603,38 @@ let LinkedInAdsProgramDriver = class LinkedInAdsProgramDriver extends BaseProgra
             if (!Number.isFinite(endMs) && row?.DecisionDate)
                 endMs = new Date(row.DecisionDate).getTime();
         }
-        const start = Number.isFinite(startMs) ? Math.max(startMs, now) : now;
-        return Number.isFinite(endMs) && endMs > start ? { start, end: endMs } : { start };
+        return platformRunSchedule(Number.isFinite(startMs) ? new Date(startMs) : null, Number.isFinite(endMs) ? new Date(endMs) : null, new Date(now));
+    }
+    /**
+     * KI-119: the sprint moved after lock (an early close pulled it forward). The campaign group and campaign were
+     * created with the OLD window as their run schedule, so without this the real ad sat waiting for the original
+     * date while the app said the sprint was running. Both objects get the window the program now carries.
+     */
+    async onWindowMoved(program, window) {
+        const user = this.requireUser();
+        if (!program.id)
+            return { rescheduled: false, note: 'LinkedIn Ads: no saved program (no id).' };
+        const refs = await this.loadRefs(program.id, user);
+        const campaignUrn = refs.find(r => r.ExternalKind === 'Campaign')?.ExternalURN ?? null;
+        if (!campaignUrn)
+            return { rescheduled: false, note: 'LinkedIn Ads: no campaign on the platform yet — nothing to move.' };
+        const groupUrn = refs.find(r => r.ExternalKind === 'CampaignGroup')?.ExternalURN ?? null;
+        const ctx = await this.resolveContext(program.brandId, user);
+        if (isLinkedInRefused(ctx)) {
+            throw new Error(`LinkedIn Ads reschedule refused: ${ctx.issues.map(i => i.message).join(' ')}`);
+        }
+        const runSchedule = platformRunSchedule(window.startDate, window.endDate);
+        const groupStart = groupUrn ? await ctx.client.campaignGroupStart(groupUrn) : null;
+        await ctx.client.setRunSchedule(campaignUrn, groupUrn, runSchedule);
+        // A group locked before KI-143 may start AFTER the moved campaign; LinkedIn will not serve it before the
+        // group's start and will not let the start move. Say so — the sprint runs, the ad waits.
+        const groupNote = groupStart != null && groupStart > runSchedule.start
+            ? ` — NOTE: its campaign group ${groupUrn} starts ${new Date(groupStart).toISOString().slice(0, 10)} and LinkedIn freezes that; the campaign cannot serve before then (KI-143)`
+            : '';
+        const fmt = (ms) => ms == null ? 'open' : new Date(ms).toISOString().slice(0, 10);
+        const note = `LinkedIn Ads: campaign ${campaignUrn} now runs ${fmt(runSchedule.start)} → ${fmt(runSchedule.end)}${groupNote}`;
+        LogStatus(`LinkedInAdsProgramDriver.onWindowMoved: ${program.name ?? program.id} — ${note}`);
+        return { rescheduled: true, note };
     }
     async loadRefs(programId, user) {
         const res = await new RunView().RunView({
@@ -455,4 +713,40 @@ LinkedInAdsProgramDriver = __decorate([
 ], LinkedInAdsProgramDriver);
 export { LinkedInAdsProgramDriver };
 export function LoadLinkedInAdsProgramDriver() { }
+/**
+ * LinkedIn's own copy rules, at propose (DRIVERS.md §11: "the only place a platform's rules live"). Lengths that
+ * LinkedIn enforces are errors in the shared parser (600 for the intro); what it merely clips is a notice.
+ */
+export function validateLinkedInCreative(config) {
+    const issues = [];
+    const creative = effectiveCreative(config);
+    if (creative.introText && creative.introText.length > INTRO_TEXT_UNCLIPPED_LENGTH) {
+        issues.push({
+            severity: 'notice', code: 'LI_INTRO_TEXT_LONG',
+            message: `The intro text is ${creative.introText.length} characters; LinkedIn shows about ${INTRO_TEXT_UNCLIPPED_LENGTH} before "…see more". Lead with what they get.`,
+        });
+    }
+    if (creative.headlines.length === 1) {
+        issues.push({ severity: 'notice', code: 'LI_SINGLE_VARIANT', message: 'One headline makes one ad; a second gives LinkedIn something to compare (R4).' });
+    }
+    return issues;
+}
+/** R2: the saved audience's own approximate count against the floor LinkedIn serves to and the ceiling Trent set. */
+export /** The one sentence a founder needs when the authorization cannot attach a conversion (KI-148). */ function conversionScopeMessage() {
+    return `the LinkedIn authorization behind this connection has no ${CONVERSION_SCOPE} scope, so a conversion cannot be attached to the campaign. `
+        + 'Request the Conversions API product on the developer app, re-authorize with that scope and Rotate the credential in Settings → Connections — until then propose with optimizeFor: "clicks".';
+}
+function audienceSizeIssues(template) {
+    const n = template.approximateMemberCount;
+    if (n === null) {
+        return [{ severity: 'notice', code: 'LI_AUDIENCE_SIZE_UNKNOWN', message: `LinkedIn reports no member count for saved audience "${template.name}".` }];
+    }
+    if (n > AUDIENCE_MAX_MEMBERS) {
+        return [{ severity: 'error', code: 'LI_AUDIENCE_TOO_LARGE', message: `Saved audience "${template.name}" is ~${n.toLocaleString('en-US')} members — over the ${AUDIENCE_MAX_MEMBERS.toLocaleString('en-US')} ceiling. Pick a narrower saved audience (CP-02 served 300M people on a location alone).` }];
+    }
+    if (n < MATCHED_AUDIENCE_MIN_MEMBERS) {
+        return [{ severity: 'error', code: 'LI_AUDIENCE_TOO_SMALL', message: `Saved audience "${template.name}" is ~${n} members — LinkedIn does not serve to fewer than ${MATCHED_AUDIENCE_MIN_MEMBERS}.` }];
+    }
+    return [];
+}
 //# sourceMappingURL=LinkedInAdsProgramDriver.js.map