@affset/mcp 0.2.0 → 0.4.0

package/dist/tools/getZoneUrl.js

@@ -1,15 +1,16 @@
 import { z } from "zod";
 import { mdCell } from "../lib/format.js";
-import { buildZoneUrl, fetchTenantIntegration, subLegend } from "../lib/integrationUrls.js";
-import { collectSubs, linkInputSchema } from "../lib/linkArgs.js";
+import { buildZoneUrl, fetchTenantIntegration, resolveLinkedSource, subLegend, templateHasParam, } from "../lib/integrationUrls.js";
+import { collectSubs, hasExplicitLinkParams, linkInputSchema, } from "../lib/linkArgs.js";
 import { errorResult, textError, textResult } from "../lib/toolResult.js";
 import { resolveZone, zonePostbackNote } from "../lib/zones.js";
 export const GET_ZONE_URL_DESCRIPTION = "Get the zone URL to paste into a traffic source's campaign settings — the /serve link " +
-    "that rotates across the zone's active campaigns. Prefilled with the sub convention " +
-    "(source_click_id + sub1..sub5) and optionally the network's cost macro. Uses the " +
-    "tenant's custom API domain when one is set. Read-only: builds the URL, changes nothing. " +
-    "For a link straight to one active campaign without targeting checks, use " +
-    "get_tracking_link instead.";
+    "that rotates across the zone's active campaigns. A zone linked to a traffic source " +
+    "renders that source's tracking template; otherwise the URL is prefilled with the sub " +
+    "convention (source_click_id + sub1..sub5) and optionally the network's cost macro. " +
+    "Uses the tenant's custom API domain when one is set. Read-only: builds the URL, " +
+    "changes nothing. For a link straight to one active campaign without targeting checks, " +
+    "use get_tracking_link instead.";
 export const getZoneUrlInputSchema = {
     zone_id: z
         .string()
@@ -30,16 +31,19 @@ export async function getZoneUrl(client, config, args) {
             return textError(zoneResult.error);
         const { zone, inactiveWarning } = zoneResult;
         const subs = collectSubs(args);
+        const linked = await resolveLinkedSource(client, zone, hasExplicitLinkParams(args));
         const url = buildZoneUrl(integration.baseUrl, zone.id, {
             sourceClickId: args.source_click_id,
             subs,
             cost: args.cost,
             subLabels: integration.subLabels,
+            template: linked.template,
         });
         // A zone URL with nothing to rotate serves the traffic-back / unsold path — the
         // single most common "my link doesn't work" report, so check it up front.
         const rotationNote = await describeRotation(client);
         const legend = subLegend(integration.subLabels, subs);
+        const templated = linked.template !== undefined;
         return textResult([
             `**Zone URL** for **${mdCell(zone.name)}** (\`${zone.id}\`) — give this to the traffic source:`,
             "",
@@ -49,19 +53,23 @@ export async function getZoneUrl(client, config, args) {
             "",
             "| Field | Value |",
             "|---|---|",
+            ...(linked.sourceLabel ? [`| Traffic source | ${linked.sourceLabel} |`] : []),
             `| Zone status | ${zone.status} |`,
             `| Rotation | ${rotationNote} |`,
             `| Postback | ${zonePostbackNote(zone)} |`,
             `| Traffic back | ${mdCell(zone.traffic_back_url ?? "—")} |`,
             ...(legend ? [`| Sub slots | ${legend} |`] : []),
             ...(inactiveWarning ? ["", inactiveWarning] : []),
+            ...linked.notes.flatMap((note) => ["", note]),
             "",
-            "Replace each `{…}` placeholder with the source's own macro and drop the sub slots " +
-                "you don't need. Values are inserted verbatim — the network expands its macros " +
-                "before the request reaches affset.",
-            args.cost
-                ? "`cost` is recorded once per /serve, on the impression row — don't also add it to a tracking link for the same traffic."
-                : "Add `cost=<network cost macro>` to import media cost and get ROI in `get_stats`.",
+            templated
+                ? "Query parameters come from the linked source's tracking template — the network " +
+                    "expands its macros before the request reaches affset. Edit them with " +
+                    "`update_traffic_source`; explicit link parameters on this tool override the template."
+                : "Replace each `{…}` placeholder with the source's own macro and drop the sub slots " +
+                    "you don't need. Values are inserted verbatim — the network expands its macros " +
+                    "before the request reaches affset.",
+            costNote(templated, linked.template, args.cost),
             "",
             "_This URL rotates across the zone's **active** campaigns. For a link that goes " +
                 "straight to one active campaign without applying targeting rules, use `get_tracking_link`._",
@@ -71,6 +79,15 @@ export async function getZoneUrl(client, config, args) {
         return errorResult(err);
     }
 }
+function costNote(templated, template, costArg) {
+    const hasCost = templated ? templateHasParam(template, "cost") : Boolean(costArg);
+    if (hasCost) {
+        return "`cost` is recorded once per /serve, on the impression row — don't also add it to a tracking link for the same traffic.";
+    }
+    return templated
+        ? "Add a `cost=<network cost macro>` parameter to the source's tracking template to import media cost and get ROI in `get_stats`."
+        : "Add `cost=<network cost macro>` to import media cost and get ROI in `get_stats`.";
+}
 /** Cheap active-campaign count; degrades to a neutral note rather than failing. */
 async function describeRotation(client) {
     try {

package/dist/tools/listConversions.d.ts

@@ -8,6 +8,7 @@ export declare const listConversionsInputSchema: {
     offset: z.ZodDefault<z.ZodNumber>;
     sort: z.ZodDefault<z.ZodEnum<["created_at", "ad_event_id", "click_id"]>>;
     order: z.ZodDefault<z.ZodEnum<["asc", "desc"]>>;
+    paid_only: z.ZodOptional<z.ZodBoolean>;
     click_id: z.ZodOptional<z.ZodString>;
     source_click_id: z.ZodOptional<z.ZodString>;
     type: z.ZodOptional<z.ZodString>;
@@ -19,6 +20,7 @@ type ListConversionsArgs = {
     offset: number;
     sort: (typeof SORT_FIELDS)[number];
     order: "asc" | "desc";
+    paid_only?: boolean;
     click_id?: string;
     source_click_id?: string;
     type?: string;

package/dist/tools/listConversions.js

@@ -6,14 +6,26 @@ import { SUB_KEYS, } from "../types.js";
 const SORT_FIELDS = ["created_at", "ad_event_id", "click_id"];
 export const LIST_CONVERSIONS_DESCRIPTION = "List recent conversion records (audit trail) for debugging payouts and pixel params. " +
     "Shows payout, spend, pixel `type`, source_click_id, click_id, subs, postback outcome, " +
-    "and the raw payload. API supports pagination/sort only — optional click_id / " +
-    "source_click_id / type / payload_contains / zero_payout filters run client-side on " +
-    "the current page. Does not include campaign_id/zone_id (not returned by the API).";
+    "and the raw payload. `paid_only: true` drops informative conversions server-side — " +
+    "rows recorded with postback_skipped=non_goal_type because the pixel type missed the " +
+    "campaign's payout_goal_type. Silent conversions and other skip reasons still come back " +
+    "(not a payout>0 filter). Default false, all rows. Beyond pagination/sort/paid_only, " +
+    "the optional click_id / source_click_id / type / payload_contains / zero_payout filters " +
+    "run client-side on the current page. Does not include campaign_id/zone_id (not returned " +
+    "by the API).";
 export const listConversionsInputSchema = {
     limit: z.number().int().min(1).max(100).default(20).describe("Page size (1–100). Default 20."),
     offset: z.number().int().min(0).default(0).describe("Pagination offset. Default 0."),
     sort: z.enum(SORT_FIELDS).default("created_at").describe("Sort field. Default created_at."),
     order: z.enum(["asc", "desc"]).default("desc").describe("Sort order. Default desc."),
+    paid_only: z
+        .boolean()
+        .optional()
+        .describe("true drops informative conversions — rows recorded with " +
+        "postback_skipped=non_goal_type because the pixel type missed the campaign's " +
+        "payout_goal_type. Silent conversions and other skip reasons still come back " +
+        "(not a payout>0 filter). Server-side (filters the whole dataset, not just this page). " +
+        "Works without payout visibility. Default false (all rows)."),
     click_id: z
         .string()
         .min(1)
@@ -42,13 +54,17 @@ export const listConversionsInputSchema = {
 };
 export async function listConversions(client, args) {
     try {
+        const query = {
+            limit: args.limit,
+            offset: args.offset,
+            sort: args.sort,
+            order: args.order,
+        };
+        // The API accepts only the literal strings "true"/"false"; omitted = false.
+        if (args.paid_only !== undefined)
+            query.paid_only = String(args.paid_only);
         const [data, settings] = await Promise.all([
-            client.get("/api/conversions", {
-                limit: args.limit,
-                offset: args.offset,
-                sort: args.sort,
-                order: args.order,
-            }),
+            client.get("/api/conversions", query),
             // One read covers both the sub labels and the zone timestamps are shown in.
             client.get("/api/tenant").catch(() => ({})),
         ]);
@@ -67,6 +83,8 @@ export async function listConversions(client, args) {
         const total = pagination?.total ?? all.length;
         const clientFiltered = filtered.length !== all.length;
         const filterBits = [];
+        if (args.paid_only)
+            filterBits.push("paid_only");
         if (args.click_id)
             filterBits.push(`click_id=${args.click_id}`);
         if (args.source_click_id)
@@ -98,7 +116,8 @@ export async function listConversions(client, args) {
                 ]
                 : []),
             "",
-            "_API has no campaign/zone/date filters — page with limit/offset, or filter this page._",
+            "_API has no campaign/zone/date filters. `paid_only` is server-side; other optional " +
+                "filters apply to this page. Page with limit/offset._",
             payoutHidden
                 ? "_`payout` is hidden for this role — the column shows `—` for every row._"
                 : "_`$0` payout with a non-empty type often means payout_goal_type mismatch or no payout rule._",

package/dist/tools/listSourceBids.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type AffsetClient } from "../client.js";
+export declare const LIST_SOURCE_BIDS_DESCRIPTION: string;
+export declare const listSourceBidsInputSchema: {
+    traffic_source_id: z.ZodString;
+};
+type ListSourceBidsArgs = {
+    traffic_source_id: string;
+};
+export declare function listSourceBids(client: AffsetClient, args: ListSourceBidsArgs): Promise<CallToolResult>;
+export {};

package/dist/tools/listSourceBids.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { AffsetApiError } from "../client.js";
+import { formatBidsTable, LARGE_INCREASE_FACTOR, networkErrorText } from "../lib/bids.js";
+import { errorResult, textError, textResult } from "../lib/toolResult.js";
+export const LIST_SOURCE_BIDS_DESCRIPTION = "List the network campaigns of one traffic source with their CURRENT bids, read live " +
+    "from the network account (ExoClick, TrafficStars or RichAds preset with an API token). " +
+    "Shows status, pricing model (CPC/CPM/…), the bid in USD, and the last bid change that " +
+    "entered Affset's mutation stage. Use before set_source_bid to see what a campaign bids " +
+    "today. Read-only.";
+export const listSourceBidsInputSchema = {
+    traffic_source_id: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("Traffic source id (from list_traffic_sources) — must have a network API token."),
+};
+export async function listSourceBids(client, args) {
+    try {
+        let res;
+        try {
+            res = await client.get(`/api/traffic-sources/${encodeURIComponent(args.traffic_source_id)}/bids`);
+        }
+        catch (err) {
+            if (err instanceof AffsetApiError && err.status === 404) {
+                return textError(`Traffic source \`${args.traffic_source_id}\` not found in this namespace.`);
+            }
+            if (err instanceof AffsetApiError && err.status === 422) {
+                return textError(`${err.message} Bids can be read for sources created from the exoclick, trafficstars ` +
+                    "or richads preset once an api_token is stored (update_traffic_source).");
+            }
+            if (err instanceof AffsetApiError && err.status === 502) {
+                return textError(`The network refused the request: ${networkErrorText(err.message)}`);
+            }
+            throw err;
+        }
+        return textResult([
+            `**Network campaigns and bids** (${res.campaigns.length}, read from the network at ` +
+                `${new Date(res.fetched_at).toISOString()}):`,
+            "",
+            formatBidsTable(res.campaigns),
+            "",
+            "_Bids are in USD: CPM per 1,000 impressions, CPC per click. Change one with " +
+                "`set_source_bid` (dry-run first). Increases above " +
+                `${LARGE_INCREASE_FACTOR}× the current bid need \`allow_large_increase: true\`._`,
+        ].join("\n"));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+//# sourceMappingURL=listSourceBids.js.map

package/dist/tools/listTrafficSources.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { AffsetClient } from "../client.js";
+import { TRAFFIC_SOURCE_STATUSES } from "../types.js";
+export declare const LIST_TRAFFIC_SOURCES_DESCRIPTION: string;
+export declare const listTrafficSourcesInputSchema: {
+    status: z.ZodOptional<z.ZodEnum<["active", "archived"]>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+};
+type ListTrafficSourcesArgs = {
+    status?: (typeof TRAFFIC_SOURCE_STATUSES)[number];
+    limit: number;
+    offset: number;
+};
+export declare function listTrafficSources(client: AffsetClient, args: ListTrafficSourcesArgs): Promise<CallToolResult>;
+export {};

package/dist/tools/listTrafficSources.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { capUntrusted, mdCell } from "../lib/format.js";
+import { errorResult, textResult } from "../lib/toolResult.js";
+import { TRAFFIC_SOURCE_STATUSES } from "../types.js";
+/** Templates run to 2000 chars server-side; the table shows enough to identify one. */
+const TEMPLATE_PREVIEW_MAX = 150;
+export const LIST_TRAFFIC_SOURCES_DESCRIPTION = "List the tenant's traffic sources — the ad networks bought from, each with the " +
+    "tracking template its linked zones render in get_zone_url/get_tracking_link and an " +
+    "optional postback template. The stored network API token is write-only and shown " +
+    "only as set/none. Read-only.";
+export const listTrafficSourcesInputSchema = {
+    status: z
+        .enum(TRAFFIC_SOURCE_STATUSES)
+        .optional()
+        .describe("Filter by status. Omit for all sources."),
+    limit: z.number().int().min(1).max(100).default(50).describe("Sources per page (1–100)."),
+    offset: z.number().int().min(0).default(0).describe("Pagination offset."),
+};
+export async function listTrafficSources(client, args) {
+    try {
+        const query = {
+            limit: args.limit,
+            offset: args.offset,
+            sort: "created_at",
+            order: "desc",
+        };
+        if (args.status)
+            query.status = args.status;
+        const res = await client.get("/api/traffic-sources", query);
+        const sources = res.traffic_sources ?? [];
+        const total = res.pagination?.total ?? sources.length;
+        if (sources.length === 0) {
+            return textResult(args.status
+                ? `No ${args.status} traffic sources.`
+                : "No traffic sources yet. Create one with `create_traffic_source` — start from " +
+                    "a preset to get the network's tracking template ready-made, then link zones " +
+                    "to it via `create_zone`/`update_zone` `traffic_source_id`.");
+        }
+        const rows = sources.map((s) => [
+            `| ${mdCell(s.name)} `,
+            `| \`${mdCell(s.id)}\` `,
+            `| ${s.preset ? mdCell(s.preset) : "—"} `,
+            `| ${mdCell(s.status)} `,
+            `| ${s.has_api_token ? "set" : "—"} `,
+            `| ${s.tracking_template ? mdCell(capUntrusted(s.tracking_template, TEMPLATE_PREVIEW_MAX)) : "—"} `,
+            `| ${s.postback_template ? mdCell(capUntrusted(s.postback_template, TEMPLATE_PREVIEW_MAX)) : "—"} |`,
+        ].join(""));
+        return textResult([
+            `**Traffic sources** (${sources.length} of ${total}):`,
+            "",
+            "| Name | Id | Preset | Status | API token | Tracking template | Postback template |",
+            "|---|---|---|---|---|---|---|",
+            ...rows,
+            "",
+            "_Zones linked to a source render its tracking template in `get_zone_url` / " +
+                "`get_tracking_link`. Edit a source with `update_traffic_source`._",
+        ].join("\n"));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+//# sourceMappingURL=listTrafficSources.js.map

package/dist/tools/listZones.js

@@ -3,8 +3,8 @@ import { mdCell } from "../lib/format.js";
 import { errorResult } from "../lib/toolResult.js";
 import { ZONE_STATUSES } from "../types.js";
 export const LIST_ZONES_DESCRIPTION = "List traffic-source zones in the current namespace. Filter by status and optionally " +
-    "by name (client-side contains match). Returns id, name, status, postback_url, " +
-    "site_url, publisher. Paginated (default 20, max 100).";
+    "by name (client-side contains match). Returns id, name, linked traffic source, " +
+    "status, postback_url, site_url, publisher. Paginated (default 20, max 100).";
 export const listZonesInputSchema = {
     status: z.enum(ZONE_STATUSES).optional().describe("Filter by zone status."),
     name_contains: z
@@ -54,11 +54,16 @@ function renderTable(zones) {
     if (zones.length === 0)
         return "_No zones matched._";
     const lines = [
-        "| ID | Name | Status | Postback | Site | Publisher |",
-        "|---|---|---|---|---|---|",
+        "| ID | Name | Source | Status | Postback | Site | Publisher |",
+        "|---|---|---|---|---|---|---|",
     ];
     for (const z of zones) {
-        lines.push(`| \`${z.id}\` | ${mdCell(z.name)} | ${z.status} | ${z.postback_url ? mdCell(shortUrl(z.postback_url)) : "⚠️ none"} | ${mdCell(shortUrl(z.site_url))} | ${mdCell(z.user_email ?? "—")} |`);
+        const source = z.traffic_source_name
+            ? mdCell(z.traffic_source_name)
+            : z.traffic_source_id
+                ? `\`${mdCell(z.traffic_source_id)}\``
+                : "—";
+        lines.push(`| \`${z.id}\` | ${mdCell(z.name)} | ${source} | ${z.status} | ${z.postback_url ? mdCell(shortUrl(z.postback_url)) : "⚠️ none"} | ${mdCell(shortUrl(z.site_url))} | ${mdCell(z.user_email ?? "—")} |`);
     }
     return lines.join("\n");
 }

package/dist/tools/setSourceBid.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type AffsetClient } from "../client.js";
+export declare const SET_SOURCE_BID_DESCRIPTION: string;
+export declare const setSourceBidInputSchema: {
+    traffic_source_id: z.ZodString;
+    network_campaign_id: z.ZodEffects<z.ZodString, string, string>;
+    bid: z.ZodEffects<z.ZodNumber, number, number>;
+    expected_current_bid: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    allow_large_increase: z.ZodDefault<z.ZodBoolean>;
+    confirm: z.ZodDefault<z.ZodBoolean>;
+};
+type SetSourceBidArgs = {
+    traffic_source_id: string;
+    network_campaign_id: string;
+    bid: number;
+    expected_current_bid?: number | null;
+    allow_large_increase: boolean;
+    confirm: boolean;
+};
+export declare function setSourceBid(client: AffsetClient, args: SetSourceBidArgs): Promise<CallToolResult>;
+export {};

package/dist/tools/setSourceBid.js

@@ -0,0 +1,195 @@
+import { z } from "zod";
+import { AffsetApiError } from "../client.js";
+import { BID_DECIMALS, bidsMatch, describeBidChange, formatBid, isLargeIncrease, LARGE_INCREASE_FACTOR, NETWORK_NAME_MAX, networkErrorText, pricingModelLabel, } from "../lib/bids.js";
+import { capUntrusted, mdCell } from "../lib/format.js";
+import { errorResult, textError, textResult } from "../lib/toolResult.js";
+/** Mirrors the API (docs/api.md § Set bid). */
+const MAX_BID = 1000;
+const MIN_BID = 10 ** -BID_DECIMALS;
+/** Error responses may include the reserved audit row, even if finalization failed. */
+const bidErrorDetailsSchema = z.object({
+    code: z.string().optional(),
+    change: z
+        .object({ id: z.string(), status: z.enum(["pending", "applied", "failed"]) })
+        .nullable()
+        .optional(),
+});
+export const SET_SOURCE_BID_DESCRIPTION = "Set one network campaign's bid at the traffic source's network account (ExoClick, " +
+    "TrafficStars or RichAds). The bid is in USD using the campaign's existing pricing model " +
+    "(for RichAds: CPM for pops, CPC for push/display), and the network applies its own minimum. " +
+    "The write is recorded in the source's bid " +
+    "history and reported as applied only when the network echoes the new value. Raising a " +
+    `bid above ${LARGE_INCREASE_FACTOR}× the current one is refused unless allow_large_increase ` +
+    "is true. The confirmed write includes the live bid just reviewed, so a concurrent network " +
+    "change is refused instead of overwritten. DRY-RUN by default; pass confirm=true to apply.";
+export const setSourceBidInputSchema = {
+    traffic_source_id: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("Traffic source id (from list_traffic_sources)."),
+    network_campaign_id: z
+        .string()
+        .trim()
+        .regex(/^\d{1,19}$/, "network_campaign_id must be the network's numeric campaign id")
+        .refine((value) => Number.isSafeInteger(Number(value)) && Number(value) > 0, "network_campaign_id must be a positive numeric campaign id within the supported range")
+        .describe("The network's numeric campaign id — the value in sub4, or from list_source_bids."),
+    bid: z
+        .number()
+        .min(MIN_BID)
+        .max(MAX_BID)
+        .refine((value) => Math.abs(value * 10 ** BID_DECIMALS - Math.round(value * 10 ** BID_DECIMALS)) <= 1e-6, `bid must have at most ${BID_DECIMALS} decimal places`)
+        .describe(`New bid in USD (at most ${BID_DECIMALS} decimals, at most ${MAX_BID}).`),
+    expected_current_bid: z
+        .number()
+        .finite()
+        .nonnegative()
+        .nullable()
+        .optional()
+        .describe("The current bid shown by this tool's dry run (including null). Required with confirm=true " +
+        "so a bid that changed after review cannot be overwritten."),
+    allow_large_increase: z
+        .boolean()
+        .default(false)
+        .describe(`Required to raise a bid above ${LARGE_INCREASE_FACTOR}× its current value. ` +
+        "Only pass it after the operator has seen the current bid and asked for the increase."),
+    confirm: z
+        .boolean()
+        .default(false)
+        .describe("false = dry-run preview (default). true = send the bid to the network."),
+};
+function campaignLine(campaign) {
+    const name = campaign.name ? mdCell(capUntrusted(campaign.name, NETWORK_NAME_MAX)) : "(unnamed)";
+    return (`**${name}** (\`${mdCell(campaign.network_campaign_id)}\`, ${campaign.status}, ` +
+        `${pricingModelLabel(campaign.pricing_model)})`);
+}
+export async function setSourceBid(client, args) {
+    try {
+        const scaled = args.bid * 10 ** BID_DECIMALS;
+        if (!Number.isFinite(args.bid) || args.bid < MIN_BID || args.bid > MAX_BID) {
+            return textError(`bid must be between ${MIN_BID} and ${MAX_BID} USD.`);
+        }
+        if (Math.abs(scaled - Math.round(scaled)) > 1e-6) {
+            return textError(`bid must have at most ${BID_DECIMALS} decimal places.`);
+        }
+        if (args.confirm && args.expected_current_bid === undefined) {
+            return textError("Not applied: confirm=true requires expected_current_bid from this tool's dry run. " +
+                "Run the dry run again, review the current bid, then pass back the value it shows.");
+        }
+        const sourcePath = `/api/traffic-sources/${encodeURIComponent(args.traffic_source_id)}`;
+        const campaignId = String(Number(args.network_campaign_id));
+        // Read first, always: the operator confirms against the bid the network holds
+        // right now, not against a remembered number.
+        let current;
+        try {
+            const bids = await client.get(`${sourcePath}/bids`);
+            current = bids.campaigns.find((campaign) => campaign.network_campaign_id === campaignId);
+        }
+        catch (err) {
+            if (err instanceof AffsetApiError && err.status === 404) {
+                return textError(`Traffic source \`${args.traffic_source_id}\` not found in this namespace.`);
+            }
+            if (err instanceof AffsetApiError && (err.status === 422 || err.status === 502)) {
+                return textError(err.status === 422
+                    ? `${err.message} Bids need an exoclick, trafficstars or richads source with an api_token.`
+                    : `The network refused the request: ${networkErrorText(err.message)}`);
+            }
+            throw err;
+        }
+        if (current === undefined) {
+            return textError(`Campaign \`${campaignId}\` is not in this network account (list_source_bids shows the ` +
+                "campaigns it has). Check the sub4 value against the source's tracking template.");
+        }
+        const large = isLargeIncrease(current.bid, args.bid);
+        const lines = [`${campaignLine(current)}: ${describeBidChange(current.bid, args.bid)}`];
+        if (bidsMatch(current.bid, args.bid)) {
+            return textResult(`Nothing to change — ${campaignLine(current)} already bids ${formatBid(current.bid)}.`);
+        }
+        if (large) {
+            lines.push("", `⚠️ This raises the bid more than ${LARGE_INCREASE_FACTOR}× (${formatBid(current.bid)} → ` +
+                `${formatBid(args.bid)}). The API refuses it unless \`allow_large_increase: true\` ` +
+                `is passed${args.allow_large_increase ? " — it is." : "."}`);
+        }
+        if (!args.confirm) {
+            const reviewedBid = current.bid === null ? "null" : String(current.bid);
+            return textResult([
+                `**Dry run** — would set the bid at traffic source \`${args.traffic_source_id}\`.`,
+                "",
+                ...lines,
+                "",
+                large && !args.allow_large_increase
+                    ? "Call again with `confirm: true`, " +
+                        `\`expected_current_bid: ${reviewedBid}\`, **and** ` +
+                        "`allow_large_increase: true` to apply."
+                    : `Call again with \`confirm: true\` and \`expected_current_bid: ${reviewedBid}\` to apply.`,
+            ].join("\n"));
+        }
+        // The early confirmation check above narrows this to number|null here.
+        const reviewedBid = args.expected_current_bid;
+        if (!bidsMatch(reviewedBid, current.bid)) {
+            return textError(`Not applied: the campaign bid changed after review (${formatBid(reviewedBid)} → ` +
+                `${formatBid(current.bid)}). Run the dry run again and review the new current bid.`);
+        }
+        let applied;
+        try {
+            applied = await client.post(`${sourcePath}/bids`, {
+                network_campaign_id: campaignId,
+                bid: args.bid,
+                expected_current_bid: reviewedBid,
+                ...(args.allow_large_increase ? { allow_large_increase: true } : {}),
+            });
+        }
+        catch (err) {
+            // Once POST starts, a lost response or failed verification is not proof
+            // that the network kept the previous bid. Read live state before retrying.
+            if (!(err instanceof AffsetApiError) || err.status === 0 || err.status >= 500) {
+                const message = err instanceof Error ? err.message : String(err);
+                return textError(`Bid write outcome is unconfirmed: ${networkErrorText(message)} ` +
+                    "The network may have applied the bid. Check list_source_bids for the current bid " +
+                    "before retrying.");
+            }
+            const parsed = bidErrorDetailsSchema.safeParse(err.body);
+            const details = parsed.success ? parsed.data : undefined;
+            if (err.status === 404) {
+                return textError(`Not applied: campaign \`${mdCell(campaignId)}\` is no longer in this network account. ` +
+                    "Refresh with list_source_bids.");
+            }
+            if (err.status === 409) {
+                if (details?.code === "BID_CHANGED") {
+                    return textError(`Not applied: ${err.message} Run list_source_bids and review the new current bid ` +
+                        "before confirming again.");
+                }
+                if (details?.code === "CONFIRM_LARGE_INCREASE") {
+                    return textError(`Refused: ${err.message} Nothing was sent to the network. Repeat with ` +
+                        "`allow_large_increase: true` if the operator really wants this increase.");
+                }
+            }
+            if (err.status === 422) {
+                const change = details?.change;
+                const history = change?.status === "pending"
+                    ? ` Change \`${mdCell(change.id)}\` remains pending in history. ` +
+                        "Refresh with list_source_bids before retrying."
+                    : change?.status === "failed"
+                        ? " The attempt is recorded in the source's bid history as failed " +
+                            `(change \`${mdCell(change.id)}\`).`
+                        : "";
+                return textError(`Bid request refused: ${networkErrorText(err.message)}${history}`);
+            }
+            throw err;
+        }
+        return textResult([
+            `✅ Bid set at the network: ${campaignLine(current)} now bids ` +
+                `${formatBid(applied.campaign.bid)} (was ${formatBid(applied.change.previous_bid)}).`,
+            "",
+            applied.audit_finalized
+                ? `Recorded as change \`${mdCell(applied.change.id)}\`` +
+                    `${applied.change.changed_by ? ` by ${mdCell(applied.change.changed_by)}` : ""}.`
+                : `⚠️ The network applied the bid, but change \`${mdCell(applied.change.id)}\` remains ` +
+                    "pending in history. Refresh with list_source_bids before retrying.",
+        ].join("\n"));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+//# sourceMappingURL=setSourceBid.js.map

package/dist/tools/updateTrafficSource.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type AffsetClient } from "../client.js";
+import { TRAFFIC_SOURCE_STATUSES } from "../types.js";
+export declare const UPDATE_TRAFFIC_SOURCE_DESCRIPTION: string;
+export declare const updateTrafficSourceInputSchema: {
+    traffic_source_id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    tracking_template: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
+    postback_template: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
+    api_token: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
+    status: z.ZodOptional<z.ZodEnum<["active", "archived"]>>;
+    confirm: z.ZodDefault<z.ZodBoolean>;
+};
+type UpdateTrafficSourceArgs = {
+    traffic_source_id: string;
+    name?: string;
+    tracking_template?: string | null;
+    postback_template?: string | null;
+    api_token?: string | null;
+    status?: (typeof TRAFFIC_SOURCE_STATUSES)[number];
+    confirm: boolean;
+};
+export declare function updateTrafficSource(client: AffsetClient, args: UpdateTrafficSourceArgs): Promise<CallToolResult>;
+export {};