mcp-meta-ads-incrementality 0.2.0 → 0.2.2

package/dist/tools/campaign-build.d.ts

@@ -0,0 +1,117 @@
+export interface CreateCampaignInput {
+    account_id: string;
+    name: string;
+    objective: string;
+    status?: 'PAUSED' | 'ACTIVE';
+    special_ad_categories?: string[];
+    buying_type?: 'AUCTION' | 'RESERVED';
+    daily_budget?: number;
+    lifetime_budget?: number;
+}
+export interface CreateCampaignResult {
+    campaign_id: string;
+    account_id: string;
+    name: string;
+    status: string;
+}
+export declare function createCampaign(input: CreateCampaignInput, accessToken: string): Promise<CreateCampaignResult>;
+export interface CreateAdSetInput {
+    account_id: string;
+    campaign_id: string;
+    name: string;
+    optimization_goal: string;
+    billing_event: 'IMPRESSIONS' | 'LINK_CLICKS' | 'POST_ENGAGEMENT' | 'THRUPLAY';
+    bid_strategy?: 'LOWEST_COST_WITHOUT_CAP' | 'LOWEST_COST_WITH_BID_CAP' | 'COST_CAP';
+    bid_amount?: number;
+    targeting: Record<string, unknown>;
+    status?: 'PAUSED' | 'ACTIVE';
+    daily_budget?: number;
+    lifetime_budget?: number;
+    promoted_object?: Record<string, unknown>;
+    destination_type?: string;
+    attribution_spec?: Array<{
+        event_type: string;
+        window_days: number;
+    }>;
+    is_incremental_attribution_enabled?: boolean;
+    start_time?: string;
+    end_time?: string;
+}
+export interface CreateAdSetResult {
+    adset_id: string;
+    account_id: string;
+    campaign_id: string;
+    name: string;
+    status: string;
+}
+export declare function createAdSet(input: CreateAdSetInput, accessToken: string): Promise<CreateAdSetResult>;
+export interface CallToAction {
+    type: string;
+    value?: {
+        link?: string;
+        lead_gen_form_id?: string;
+    };
+}
+export interface CreateAdCreativeInput {
+    account_id: string;
+    name: string;
+    page_id: string;
+    image_hash?: string;
+    link: string;
+    /** Single primary text. Mutually exclusive with `messages`. */
+    message?: string;
+    /** Up to 5 primary texts (Flexible Ads / asset_feed_spec). */
+    messages?: string[];
+    /** Single headline. Mutually exclusive with `headlines`. */
+    headline?: string;
+    /** Up to 5 headlines. */
+    headlines?: string[];
+    /** Single description. Mutually exclusive with `descriptions`. */
+    description?: string;
+    /** Up to 5 descriptions. */
+    descriptions?: string[];
+    call_to_action?: CallToAction;
+    /** Shortcut: builds call_to_action={type:'SIGN_UP', value:{lead_gen_form_id}}. */
+    lead_gen_form_id?: string;
+    url_tags?: string;
+    /** Optional Instagram business account id for cross-posting. */
+    instagram_actor_id?: string;
+}
+export interface CreateAdCreativeResult {
+    creative_id: string;
+    account_id: string;
+    name: string;
+    /** Whether the creative used asset_feed_spec (multi-variant) or legacy object_story_spec. */
+    mode: 'asset_feed_spec' | 'object_story_spec';
+}
+export declare function createAdCreative(input: CreateAdCreativeInput, accessToken: string): Promise<CreateAdCreativeResult>;
+export interface CreateAdInput {
+    account_id: string;
+    name: string;
+    adset_id: string;
+    creative_id: string;
+    status?: 'PAUSED' | 'ACTIVE';
+}
+export interface CreateAdResult {
+    ad_id: string;
+    account_id: string;
+    adset_id: string;
+    creative_id: string;
+    name: string;
+    status: string;
+}
+export declare function createAd(input: CreateAdInput, accessToken: string): Promise<CreateAdResult>;
+export interface UploadImageInput {
+    account_id: string;
+    /** Base64-encoded image bytes. Prefer for tests / when caller already has bytes. */
+    image_bytes?: string;
+    /** Local file path. If provided, the file is read and base64-encoded. */
+    image_path?: string;
+}
+export interface UploadImageResult {
+    image_hash: string;
+    url: string;
+    account_id: string;
+}
+export declare function uploadImage(input: UploadImageInput, accessToken: string): Promise<UploadImageResult>;
+//# sourceMappingURL=campaign-build.d.ts.map

package/dist/tools/campaign-build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaign-build.d.ts","sourceRoot":"","sources":["../../src/tools/campaign-build.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,WAAW,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,EAC1B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,CAAC,CAe/B;AAMD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,aAAa,GAAG,aAAa,GAAG,iBAAiB,GAAG,UAAU,CAAC;IAC9E,YAAY,CAAC,EAAE,yBAAyB,GAAG,0BAA0B,GAAG,UAAU,CAAC;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,kCAAkC,CAAC,EAAE,OAAO,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,EACvB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAyC5B;AAMD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,YAAY,CAAC;IAC9B,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAAC;CAC/C;AASD,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,qBAAqB,EAC5B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,sBAAsB,CAAC,CAkFjC;AAMD,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,CAAC,CAkBzB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,EACvB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAmB5B"}

package/dist/tools/campaign-build.js

@@ -0,0 +1,205 @@
+/**
+ * Tier 1 write tools: campaign / ad set / ad creative / ad / image upload.
+ *
+ * Defaults to PAUSED status on every object so MCP callers can build a full
+ * campaign hierarchy without accidentally going live. Callers must explicitly
+ * flip status=ACTIVE (today via meta_ads_update_object_status, or directly in
+ * Ads Manager) after review.
+ *
+ * Image uploads use Meta's `bytes` form field (base64-encoded image data) —
+ * keeps everything on the standard form-urlencoded POST shape used by lib/graph.
+ */
+import { graphPost } from '../lib/graph.js';
+function normalizeAccountId(accountId) {
+    return accountId.startsWith('act_') ? accountId : `act_${accountId}`;
+}
+export async function createCampaign(input, accessToken) {
+    const account = normalizeAccountId(input.account_id);
+    const status = input.status ?? 'PAUSED';
+    const body = {
+        name: input.name,
+        objective: input.objective,
+        status,
+        special_ad_categories: JSON.stringify(input.special_ad_categories ?? []),
+        buying_type: input.buying_type ?? 'AUCTION',
+    };
+    if (input.daily_budget !== undefined)
+        body.daily_budget = String(input.daily_budget);
+    if (input.lifetime_budget !== undefined)
+        body.lifetime_budget = String(input.lifetime_budget);
+    const res = await graphPost(`${account}/campaigns`, accessToken, body);
+    return { campaign_id: res.id, account_id: account, name: input.name, status };
+}
+export async function createAdSet(input, accessToken) {
+    if (input.daily_budget !== undefined && input.lifetime_budget !== undefined) {
+        throw new Error('createAdSet: pass daily_budget OR lifetime_budget, not both.');
+    }
+    if (input.daily_budget === undefined && input.lifetime_budget === undefined) {
+        throw new Error('createAdSet: budget required. Pass daily_budget or lifetime_budget, or set the budget on the parent campaign (CBO).');
+    }
+    const account = normalizeAccountId(input.account_id);
+    const status = input.status ?? 'PAUSED';
+    const body = {
+        name: input.name,
+        campaign_id: input.campaign_id,
+        optimization_goal: input.optimization_goal,
+        billing_event: input.billing_event,
+        bid_strategy: input.bid_strategy ?? 'LOWEST_COST_WITHOUT_CAP',
+        targeting: JSON.stringify(input.targeting),
+        status,
+    };
+    if (input.daily_budget !== undefined)
+        body.daily_budget = String(input.daily_budget);
+    if (input.lifetime_budget !== undefined)
+        body.lifetime_budget = String(input.lifetime_budget);
+    if (input.bid_amount !== undefined)
+        body.bid_amount = String(input.bid_amount);
+    if (input.promoted_object)
+        body.promoted_object = JSON.stringify(input.promoted_object);
+    if (input.destination_type)
+        body.destination_type = input.destination_type;
+    if (input.attribution_spec)
+        body.attribution_spec = JSON.stringify(input.attribution_spec);
+    if (input.is_incremental_attribution_enabled !== undefined) {
+        body.is_incremental_attribution_enabled = String(input.is_incremental_attribution_enabled);
+    }
+    if (input.start_time)
+        body.start_time = input.start_time;
+    if (input.end_time)
+        body.end_time = input.end_time;
+    const res = await graphPost(`${account}/adsets`, accessToken, body);
+    return {
+        adset_id: res.id,
+        account_id: account,
+        campaign_id: input.campaign_id,
+        name: input.name,
+        status,
+    };
+}
+function collectVariants(single, multi) {
+    const out = [];
+    if (multi && multi.length)
+        out.push(...multi);
+    else if (single)
+        out.push(single);
+    return out;
+}
+export async function createAdCreative(input, accessToken) {
+    const account = normalizeAccountId(input.account_id);
+    const messages = collectVariants(input.message, input.messages);
+    const headlines = collectVariants(input.headline, input.headlines);
+    const descriptions = collectVariants(input.description, input.descriptions);
+    if (messages.length === 0) {
+        throw new Error('createAdCreative: provide message or messages[].');
+    }
+    if (messages.length > 5 || headlines.length > 5 || descriptions.length > 5) {
+        throw new Error('createAdCreative: Meta caps primary texts / headlines / descriptions at 5 each.');
+    }
+    const callToAction = input.call_to_action ??
+        (input.lead_gen_form_id
+            ? { type: 'SIGN_UP', value: { lead_gen_form_id: input.lead_gen_form_id } }
+            : undefined);
+    const useAssetFeedSpec = messages.length > 1 || headlines.length > 1 || descriptions.length > 1;
+    const body = { name: input.name };
+    if (input.url_tags)
+        body.url_tags = input.url_tags;
+    if (useAssetFeedSpec) {
+        // Meta "Flexible Ads" / multi-variant mode (optimization_type=DEGREES_OF_FREEDOM).
+        // Shape learned from a UI-built ad on 2026-05-14:
+        //   - image_hash + CTA + link live in object_story_spec.link_data (NOT in asset_feed_spec)
+        //   - asset_feed_spec contains ONLY bodies/titles/descriptions + optimization_type
+        //   - No images[], link_urls, call_to_action_types, call_to_actions, ad_formats in asset_feed_spec
+        if (!input.image_hash) {
+            throw new Error('createAdCreative: asset_feed_spec (multi-variant) mode requires image_hash.');
+        }
+        const linkData = {
+            link: input.link,
+            image_hash: input.image_hash,
+        };
+        if (callToAction)
+            linkData.call_to_action = callToAction;
+        const objectStorySpec = {
+            page_id: input.page_id,
+            link_data: linkData,
+        };
+        if (input.instagram_actor_id)
+            objectStorySpec.instagram_actor_id = input.instagram_actor_id;
+        const assetFeedSpec = {
+            bodies: messages.map((text) => ({ text })),
+            optimization_type: 'DEGREES_OF_FREEDOM',
+        };
+        if (headlines.length)
+            assetFeedSpec.titles = headlines.map((text) => ({ text }));
+        if (descriptions.length)
+            assetFeedSpec.descriptions = descriptions.map((text) => ({ text }));
+        body.object_story_spec = JSON.stringify(objectStorySpec);
+        body.asset_feed_spec = JSON.stringify(assetFeedSpec);
+    }
+    else {
+        const linkData = {
+            link: input.link,
+            message: messages[0],
+        };
+        if (input.image_hash)
+            linkData.image_hash = input.image_hash;
+        if (headlines.length)
+            linkData.name = headlines[0];
+        if (descriptions.length)
+            linkData.description = descriptions[0];
+        if (callToAction)
+            linkData.call_to_action = callToAction;
+        const objectStorySpec = {
+            page_id: input.page_id,
+            link_data: linkData,
+        };
+        if (input.instagram_actor_id)
+            objectStorySpec.instagram_actor_id = input.instagram_actor_id;
+        body.object_story_spec = JSON.stringify(objectStorySpec);
+    }
+    const res = await graphPost(`${account}/adcreatives`, accessToken, body);
+    return {
+        creative_id: res.id,
+        account_id: account,
+        name: input.name,
+        mode: useAssetFeedSpec ? 'asset_feed_spec' : 'object_story_spec',
+    };
+}
+export async function createAd(input, accessToken) {
+    const account = normalizeAccountId(input.account_id);
+    const status = input.status ?? 'PAUSED';
+    const body = {
+        name: input.name,
+        adset_id: input.adset_id,
+        creative: JSON.stringify({ creative_id: input.creative_id }),
+        status,
+    };
+    const res = await graphPost(`${account}/ads`, accessToken, body);
+    return {
+        ad_id: res.id,
+        account_id: account,
+        adset_id: input.adset_id,
+        creative_id: input.creative_id,
+        name: input.name,
+        status,
+    };
+}
+export async function uploadImage(input, accessToken) {
+    let bytes = input.image_bytes;
+    if (!bytes && input.image_path) {
+        const { readFileSync } = await import('node:fs');
+        bytes = readFileSync(input.image_path).toString('base64');
+    }
+    if (!bytes) {
+        throw new Error('uploadImage: provide image_bytes (base64) or image_path.');
+    }
+    const account = normalizeAccountId(input.account_id);
+    const res = await graphPost(`${account}/adimages`, accessToken, {
+        bytes,
+    });
+    const first = res.images ? Object.values(res.images)[0] : undefined;
+    if (!first) {
+        throw new Error('uploadImage: response missing images.bytes — Graph returned no hash.');
+    }
+    return { image_hash: first.hash, url: first.url, account_id: account };
+}
+//# sourceMappingURL=campaign-build.js.map

package/dist/tools/campaign-build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaign-build.js","sourceRoot":"","sources":["../../src/tools/campaign-build.ts"],"names":[],"mappings":"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"}

package/dist/tools/lifecycle.d.ts

@@ -0,0 +1,32 @@
+export type ObjectStatus = 'PAUSED' | 'ACTIVE' | 'ARCHIVED' | 'DELETED';
+export interface UpdateObjectStatusInput {
+    object_id: string;
+    status: ObjectStatus;
+}
+export interface UpdateObjectStatusResult {
+    object_id: string;
+    status: ObjectStatus;
+    success: boolean;
+}
+export declare function updateObjectStatus(input: UpdateObjectStatusInput, accessToken: string): Promise<UpdateObjectStatusResult>;
+export interface UpdateBudgetInput {
+    object_id: string;
+    daily_budget?: number;
+    lifetime_budget?: number;
+}
+export interface UpdateBudgetResult {
+    object_id: string;
+    daily_budget: number | null;
+    lifetime_budget: number | null;
+    success: boolean;
+}
+export declare function updateBudget(input: UpdateBudgetInput, accessToken: string): Promise<UpdateBudgetResult>;
+export interface DeleteObjectInput {
+    object_id: string;
+}
+export interface DeleteObjectResult {
+    object_id: string;
+    success: boolean;
+}
+export declare function deleteObject(input: DeleteObjectInput, accessToken: string): Promise<DeleteObjectResult>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/tools/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/tools/lifecycle.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAMxE,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB;AAOD,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,uBAAuB,EAC9B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,wBAAwB,CAAC,CASnC;AAMD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,EACxB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,CAAC,CAmB7B;AAMD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,EACxB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,CAAC,CAG7B"}

package/dist/tools/lifecycle.js

@@ -0,0 +1,43 @@
+/**
+ * Tier 3 + 4 lifecycle tools: status toggle, budget update, delete.
+ *
+ * Meta uses the same POST /{id} endpoint for any object (campaign, ad set, ad)
+ * with `status` or budget fields, and DELETE /{id} for removal. This module
+ * exposes one tool per concern; callers pass an object_id of any type.
+ */
+import { graphDelete, graphPost } from '../lib/graph.js';
+export async function updateObjectStatus(input, accessToken) {
+    const res = await graphPost(input.object_id, accessToken, {
+        status: input.status,
+    });
+    return {
+        object_id: input.object_id,
+        status: input.status,
+        success: res.success ?? false,
+    };
+}
+export async function updateBudget(input, accessToken) {
+    if (input.daily_budget === undefined && input.lifetime_budget === undefined) {
+        throw new Error('updateBudget: pass daily_budget or lifetime_budget.');
+    }
+    if (input.daily_budget !== undefined && input.lifetime_budget !== undefined) {
+        throw new Error('updateBudget: pass daily_budget OR lifetime_budget, not both.');
+    }
+    const body = {};
+    if (input.daily_budget !== undefined)
+        body.daily_budget = String(input.daily_budget);
+    if (input.lifetime_budget !== undefined)
+        body.lifetime_budget = String(input.lifetime_budget);
+    const res = await graphPost(input.object_id, accessToken, body);
+    return {
+        object_id: input.object_id,
+        daily_budget: input.daily_budget ?? null,
+        lifetime_budget: input.lifetime_budget ?? null,
+        success: res.success ?? false,
+    };
+}
+export async function deleteObject(input, accessToken) {
+    const res = await graphDelete(input.object_id, accessToken);
+    return { object_id: input.object_id, success: res.success ?? false };
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/tools/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/tools/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAwBzD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAA8B,EAC9B,WAAmB;IAEnB,MAAM,GAAG,GAAG,MAAM,SAAS,CAAuB,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE;QAC9E,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC,CAAC;IACH,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,KAAK;KAC9B,CAAC;AACJ,CAAC;AAmBD,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAwB,EACxB,WAAmB;IAEnB,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QAC5E,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QAC5E,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;IACnF,CAAC;IAED,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACrF,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS;QAAE,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAE9F,MAAM,GAAG,GAAG,MAAM,SAAS,CAAuB,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;IACtF,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;QACxC,eAAe,EAAE,KAAK,CAAC,eAAe,IAAI,IAAI;QAC9C,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,KAAK;KAC9B,CAAC;AACJ,CAAC;AAeD,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAwB,EACxB,WAAmB;IAEnB,MAAM,GAAG,GAAG,MAAM,WAAW,CAAuB,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAClF,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,KAAK,EAAE,CAAC;AACvE,CAAC"}

package/dist/tools/url-tags.d.ts

@@ -0,0 +1,145 @@
+export interface AdSummary {
+    id: string;
+    name: string;
+    status: string;
+    effective_status?: string;
+    campaign_id: string;
+    creative_id: string;
+}
+export declare function listAdsInCampaign(campaignId: string, accessToken: string): Promise<AdSummary[]>;
+export interface LearningStageInfo {
+    status: string | null;
+    last_significant_edit_ts: number | null;
+}
+export interface AdUrlTagsInfo {
+    ad_id: string;
+    ad_name: string;
+    account_id: string;
+    campaign_id: string;
+    campaign_name: string;
+    creative_id: string;
+    object_story_id: string | null;
+    url_tags: string | null;
+    link: string | null;
+    learning_stage_info: LearningStageInfo | null;
+}
+export declare function getAdUrlTags(adId: string, accessToken: string): Promise<AdUrlTagsInfo>;
+export interface UpdateAdUrlTagsResult {
+    ad_id: string;
+    ad_name: string;
+    previous_url_tags: string | null;
+    new_url_tags: string;
+    previous_creative_id: string;
+    new_creative_id: string;
+    changed: boolean;
+    learning_before: LearningStageInfo | null;
+    learning_after: LearningStageInfo | null;
+    significant_edit_triggered: boolean | null;
+}
+/**
+ * Update url_tags via create-then-rebind WITH social-feedback preservation.
+ *
+ * The Meta UI itself forks a new creative when url_tags changes (verified by
+ * inspecting Ads Manager network calls 2026-05-05 — the internal payload
+ * shows action_metadata.type=DUPLICATION_UPGRADE and
+ * enable_social_feedback_preservation=true). Meta's relearning trigger is
+ * field-aware: changes to url_tags alone are documented as not resetting
+ * learning, when social-feedback preservation carries forward.
+ *
+ * This implementation replicates that behavior on the public Marketing API:
+ *   1. Read current creative → get object_story_id, account_id, learning_stage_info.
+ *   2. POST /act_X/adcreatives with {object_story_id, url_tags,
+ *      object_story_spec.use_page_actor_override flag implicit} — same
+ *      Page-post reference, only url_tags differs.
+ *   3. POST /{ad-id} with creative_id=<new>.
+ *   4. Re-read learning_stage_info; compare last_significant_edit_ts.
+ *
+ * If last_significant_edit_ts is unchanged, Meta did not consider the edit
+ * significant — confirming learning is preserved. If it advanced to roughly
+ * the time of our write, Meta did trigger a relearning event and the writer
+ * should be considered unsafe for active ads.
+ */
+export declare function updateAdUrlTags(adId: string, newUrlTags: string, accessToken: string, dryRun: boolean): Promise<UpdateAdUrlTagsResult>;
+export interface SwapAdLeadFormResult {
+    ad_id: string;
+    ad_name: string;
+    previous_creative_id: string;
+    new_creative_id: string;
+    previous_form_id: string | null;
+    new_form_id: string;
+    mode: 'asset_feed_spec' | 'object_story_spec';
+    changed: boolean;
+}
+/**
+ * Swap the lead form on an ad by rebuilding its creative with a new form_id.
+ *
+ * Meta creatives are immutable, so we create-then-rebind:
+ *  1. Read the ad's current creative (full spec — handles both legacy
+ *     object_story_spec and modern asset_feed_spec creatives).
+ *  2. POST /act_X/adcreatives with the same image/text spec but new
+ *     lead_gen_form_id inside the SIGN_UP CTA.
+ *  3. POST /{ad-id} with creative_id=<new> to rebind.
+ *
+ * The ad-id is unchanged. Meta may briefly re-review.
+ */
+export declare function swapAdLeadForm(adId: string, newFormId: string, accessToken: string, dryRun: boolean, ctaTypeOverride?: string): Promise<SwapAdLeadFormResult>;
+export interface RebindAdCreativeResult {
+    ad_id: string;
+    ad_name: string;
+    previous_creative_id: string;
+    new_creative_id: string;
+    changed: boolean;
+    customization_rules_preserved: boolean | null;
+}
+/**
+ * Rebind an ad to a different creative_id. Atomic. ad_id stays stable.
+ * Use with createAdCreative to do full ad rebuilds (e.g. swap form + rebuild
+ * text content) without touching the ad_id.
+ *
+ * Safety check: if the OLD creative has `asset_customization_rules` (per-placement
+ * image rules set in Ads Manager UI) and the NEW creative does not carry them
+ * forward, the rebind is REFUSED. This catches the 2026-05-14 RDR class of bug
+ * where multi-variant headline writes silently flattened custom placements by image.
+ * Pass `force=true` to override (e.g. when the new creative deliberately replaces
+ * the placement rules).
+ */
+export declare function rebindAdCreative(adId: string, newCreativeId: string, accessToken: string, dryRun: boolean, force?: boolean): Promise<RebindAdCreativeResult>;
+export interface EditCreativeTextEdits {
+    messages?: string[];
+    headlines?: string[];
+    descriptions?: string[];
+}
+export interface EditCreativeTextResult {
+    ad_id: string;
+    ad_name: string;
+    previous_creative_id: string;
+    new_creative_id: string;
+    mode: 'asset_feed_spec' | 'object_story_spec';
+    changed_fields: string[];
+    customization_rules_preserved: number;
+}
+/**
+ * Edit text fields (primary texts / headlines / descriptions) on an ad's creative
+ * while PRESERVING images, videos, asset_customization_rules (per-placement image
+ * rules set in Ads Manager UI), call_to_actions, and link_urls.
+ *
+ * For asset_feed_spec ads: replaces only the specified text arrays. Refuses the
+ * edit if the existing asset_customization_rules reference per-text labels
+ * (body_label / title_label / description_label) and the new text count differs
+ * from the old — pass force=true to override (rules may end up referencing
+ * orphaned labels and break the placement targeting).
+ *
+ * For object_story_spec (legacy single-variant) ads: replaces link_data.message
+ * (single primary text), link_data.name (single headline), link_data.description.
+ * The messages/headlines/descriptions arrays must each have length ≤ 1 in that
+ * mode.
+ */
+export declare function editCreativeText(adId: string, edits: EditCreativeTextEdits, accessToken: string, dryRun: boolean, force?: boolean): Promise<EditCreativeTextResult>;
+export interface RenameAdResult {
+    ad_id: string;
+    previous_name: string;
+    new_name: string;
+    changed: boolean;
+}
+export declare function renameAd(adId: string, newName: string, accessToken: string, dryRun: boolean): Promise<RenameAdResult>;
+//# sourceMappingURL=url-tags.d.ts.map

package/dist/tools/url-tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-tags.d.ts","sourceRoot":"","sources":["../../src/tools/url-tags.ts"],"names":[],"mappings":"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"}