@affset/mcp 0.2.0 → 0.3.0

package/dist/tools/createCampaign.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { AffsetApiError } from "../client.js";
 import { mdCell, moneyPrecise } from "../lib/format.js";
-import { buildTrackingLink, fetchTenantIntegration } from "../lib/integrationUrls.js";
+import { buildTrackingLink, fetchTenantIntegration, resolveLinkedSource, } from "../lib/integrationUrls.js";
 import { errorResult, textError, textResult } from "../lib/toolResult.js";
 import { httpUrlError } from "../lib/urls.js";
 import { resolveZone, zonePostbackNote } from "../lib/zones.js";
@@ -17,8 +17,9 @@ export const CREATE_CAMPAIGN_DESCRIPTION = "Create a campaign (offer) in the cur
     "create one first with create_team_member if needed. " +
     "Everything else gets media-buying defaults: CPA model, " +
     "rate 0 (no internal advertiser billing), created paused, a global payout rule when " +
-    "payout is given, and a ready-to-use tracking link prefilled with the sub convention " +
-    "(source_click_id + sub1..sub5, named by the tenant's sub labels). The campaign is " +
+    "payout is given, and a ready-to-use tracking link. A zone linked to a traffic source " +
+    "uses that source's tracking template; otherwise the link is prefilled with the sub " +
+    "convention (source_click_id + sub1..sub5, named by the tenant's sub labels). The campaign is " +
     "created paused, so activate it before sending traffic through either URL. " +
     "Geo whitelist applies to /serve rotation only; the tracking link itself is not geo-gated. " +
     "DRY-RUN by default; pass confirm=true to apply. No money is spent by this call; the " +
@@ -87,6 +88,7 @@ export async function createCampaign(client, config, args) {
             return textError(zoneResult.error);
         }
         const { zone, inactiveWarning } = zoneResult;
+        const linked = await resolveLinkedSource(client, zone, false);
         const name = args.name?.trim() || defaultName(offerUrl, geoCodes, args.payout);
         const geoNote = geoCodes.length
             ? `${geoCodes.join(", ")} (whitelist; enforced on /serve, not on the tracking link)`
@@ -105,6 +107,7 @@ export async function createCampaign(client, config, args) {
             `| Model | CPA, rate 0 (defaults — no internal advertiser billing) |`,
             `| Status | paused (activate before sending traffic through either URL) |`,
             `| Zone | ${mdCell(zone.name)} (\`${zone.id}\`) — ${zonePostbackNote(zone)} |`,
+            ...(linked.sourceLabel ? [`| Traffic source | ${linked.sourceLabel} |`] : []),
         ].join("\n");
         if (!args.confirm) {
             return textResult([
@@ -112,6 +115,7 @@ export async function createCampaign(client, config, args) {
                 "",
                 summaryTable,
                 ...(inactiveWarning ? ["", inactiveWarning] : []),
+                ...linked.notes.flatMap((note) => ["", note]),
                 "",
                 "Call again with `confirm: true` to create it. The tracking link is returned after create.",
             ].join("\n"));
@@ -149,9 +153,11 @@ export async function createCampaign(client, config, args) {
                 payoutNote = `⚠️ campaign created, but setting the payout rule failed: ${message}`;
             }
         }
-        // 5. Ready-to-paste tracking link with the sub convention prefilled.
+        // 5. Ready-to-paste tracking link: linked source template when present,
+        //    otherwise the generic sub convention.
         const trackingLink = buildTrackingLink(integration.baseUrl, created.id, zone.id, {
             subLabels: integration.subLabels,
+            template: linked.template,
         });
         return textResult([
             `✅ Campaign **${mdCell(created.name)}** created (id \`${created.id}\`).`,
@@ -165,16 +171,22 @@ export async function createCampaign(client, config, args) {
             `| Model | CPA, rate 0 (defaults — no internal advertiser billing) |`,
             `| Status | ${created.status || "paused"} (activate before sending traffic through either URL) |`,
             `| Zone | ${mdCell(zone.name)} (\`${zone.id}\`) — ${zonePostbackNote(zone)} |`,
+            ...(linked.sourceLabel ? [`| Traffic source | ${linked.sourceLabel} |`] : []),
             ...(inactiveWarning ? ["", inactiveWarning] : []),
+            ...linked.notes.flatMap((note) => ["", note]),
             "",
             "**Tracking link** (give this to the traffic source):",
             "```",
             trackingLink,
             "```",
-            "Replace each `{…}` placeholder with the source's macro; `{clickid}` is already " +
-                "correct for RichAds. Drop sub slots you don't need. Append `&cost={cost}` " +
-                "(the network's cost macro) to import media cost for ROI. This link returns " +
-                "404 while the campaign is paused; run it with `set_campaign_status` before use.",
+            linked.template !== undefined
+                ? "Query parameters come from the linked source's tracking template. Edit them " +
+                    "with `update_traffic_source`. This link returns 404 while the campaign is " +
+                    "paused; run it with `set_campaign_status` before use."
+                : "Replace each `{…}` placeholder with the source's macro and drop sub slots you " +
+                    "don't need. Append `&cost=<network cost macro>` to import media cost for ROI. " +
+                    "This link returns 404 while the campaign is paused; run it with " +
+                    "`set_campaign_status` before use.",
             "",
             "_Only defaults were set — use `set_targeting_rule`, `set_payout_rule`, and budget fields on `update_campaign` for the rest._",
             "_Need this link again later, or the rotating /serve URL instead? `get_tracking_link` / `get_zone_url`._",

package/dist/tools/createTrafficSource.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 CREATE_TRAFFIC_SOURCE_DESCRIPTION: string;
+export declare const createTrafficSourceInputSchema: {
+    name: z.ZodString;
+    preset: z.ZodOptional<z.ZodString>;
+    tracking_template: z.ZodOptional<z.ZodString>;
+    postback_template: z.ZodOptional<z.ZodString>;
+    api_token: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<["active", "archived"]>>;
+    confirm: z.ZodDefault<z.ZodBoolean>;
+};
+type CreateTrafficSourceArgs = {
+    name: string;
+    preset?: string;
+    tracking_template?: string;
+    postback_template?: string;
+    api_token?: string;
+    status?: (typeof TRAFFIC_SOURCE_STATUSES)[number];
+    confirm: boolean;
+};
+export declare function createTrafficSource(client: AffsetClient, args: CreateTrafficSourceArgs): Promise<CallToolResult>;
+export {};

package/dist/tools/createTrafficSource.js

@@ -0,0 +1,191 @@
+import { z } from "zod";
+import { mdCell } from "../lib/format.js";
+import { SOURCE_CLICK_ID_PARAM, templateHasParam } from "../lib/integrationUrls.js";
+import { errorResult, textError, textResult } from "../lib/toolResult.js";
+import { httpUrlError } from "../lib/urls.js";
+import { TRAFFIC_SOURCE_STATUSES, } from "../types.js";
+const NAME_MAX = 200;
+const TEMPLATE_MAX = 2000;
+const TOKEN_MAX = 500;
+export const CREATE_TRAFFIC_SOURCE_DESCRIPTION = "Create a traffic source — an ad network account bought from. Creating from a preset " +
+    "(exoclick, trafficstars, propellerads, adsterra, richads) copies the network's " +
+    "verified tracking + postback templates into an editable row; [BRACKETED] pieces in a " +
+    "postback template are account-specific values to fill in. Link zones to the source " +
+    "via create_zone/update_zone traffic_source_id, and get_zone_url renders its template. " +
+    "The api_token is stored write-only for upcoming cost sync. " +
+    "DRY-RUN by default; pass confirm=true to apply.";
+export const createTrafficSourceInputSchema = {
+    name: z
+        .string()
+        .trim()
+        .min(1)
+        .max(NAME_MAX)
+        .describe('Display name, unique per tenant — e.g. "ExoClick — main".'),
+    preset: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Network preset id to copy templates from (e.g. exoclick, trafficstars, " +
+        "propellerads, adsterra, richads). The row stays fully editable and remembers " +
+        "its preset. Omit for a custom source."),
+    tracking_template: z
+        .string()
+        .max(TEMPLATE_MAX)
+        .optional()
+        .describe("Query string appended to the zone URL — our param names on the left, the " +
+        "network's macros on the right. Overrides the preset's template. Must not start " +
+        "with ? or &."),
+    postback_template: z
+        .string()
+        .max(TEMPLATE_MAX)
+        .optional()
+        .describe("The network's S2S conversion endpoint using our postback macros " +
+        "({source_click_id}, {payout}). Overrides the preset's template. Prefills the " +
+        "linked zones' postback_url suggestion — never applied automatically."),
+    api_token: z
+        .string()
+        .min(1)
+        .max(TOKEN_MAX)
+        .optional()
+        .describe("Network API credential for upcoming cost sync. Stored write-only — reads only " +
+        "ever return has_api_token."),
+    status: z.enum(TRAFFIC_SOURCE_STATUSES).optional().describe("active (default) or archived."),
+    confirm: z
+        .boolean()
+        .default(false)
+        .describe("false = dry-run preview (default). true = create the traffic source."),
+};
+export async function createTrafficSource(client, args) {
+    try {
+        const trackingTemplate = args.tracking_template?.trim();
+        if (trackingTemplate && /^[?&]/.test(trackingTemplate)) {
+            return textError("tracking_template must not start with ? or & — it is appended after ? automatically.");
+        }
+        if (args.postback_template?.trim()) {
+            const err = httpUrlError(args.postback_template.trim(), "postback_template");
+            if (err)
+                return textError(err);
+        }
+        const apiToken = args.api_token?.trim();
+        if (args.api_token !== undefined && !apiToken) {
+            return textError("api_token must be a non-empty string.");
+        }
+        // The server copies preset templates on create; the catalog is fetched only
+        // to preview them in the dry run. An unreadable catalog is not an error —
+        // the server stays the arbiter of preset validity on the actual create.
+        const lookup = args.preset
+            ? await fetchPreset(client, args.preset)
+            : { state: "none" };
+        if (lookup.state === "unknown") {
+            const listed = lookup.ids.length > 0
+                ? `Valid ids: ${lookup.ids.map((id) => `\`${mdCell(id)}\``).join(", ")}.`
+                : "The preset catalog was empty.";
+            return textError(`Unknown preset \`${mdCell(args.preset)}\`. ${listed} Omit preset for a custom source.`);
+        }
+        const preset = lookup.state === "found" ? lookup.preset : undefined;
+        // Catalog ids are lowercase; send the canonical id when we have it so
+        // "ExoClick" still creates, including when the catalog itself is down.
+        const presetId = lookup.state === "found"
+            ? lookup.preset.id
+            : args.preset
+                ? args.preset.toLowerCase()
+                : undefined;
+        const presetFallbackCell = lookup.state === "unavailable" ? "_(copied from preset — catalog could not be read)_" : "—";
+        const effectiveTracking = trackingTemplate !== undefined ? trackingTemplate : (preset?.tracking_template ?? "");
+        const warnings = [];
+        if (effectiveTracking && !templateHasParam(effectiveTracking, SOURCE_CLICK_ID_PARAM)) {
+            warnings.push("⚠️ The tracking template has no `source_click_id=` parameter — the " +
+                "network's click token will not be captured on linked zones' URLs.");
+        }
+        const summaryTable = [
+            "| Field | Value |",
+            "|---|---|",
+            `| Name | ${mdCell(args.name)} |`,
+            `| Preset | ${presetId ? mdCell(presetId) : "— (custom)"} |`,
+            `| Tracking template | ${templateCell(trackingTemplate, preset?.tracking_template, presetFallbackCell)} |`,
+            `| Postback template | ${templateCell(args.postback_template?.trim(), preset?.postback_template, presetFallbackCell)} |`,
+            `| API token | ${apiToken ? "(set — stored write-only)" : "—"} |`,
+            `| Status | ${args.status ?? "active"} |`,
+            ...(preset?.notes ? [`| Preset notes | ${mdCell(preset.notes)} |`] : []),
+        ].join("\n");
+        if (!args.confirm) {
+            return textResult([
+                "**Dry run** — would create a traffic source with:",
+                "",
+                summaryTable,
+                ...(warnings.length ? ["", ...warnings] : []),
+                "",
+                "Call again with `confirm: true` to create it.",
+            ].join("\n"));
+        }
+        const body = { name: args.name };
+        if (presetId !== undefined)
+            body.preset = presetId;
+        if (args.tracking_template !== undefined)
+            body.tracking_template = trackingTemplate ?? "";
+        if (args.postback_template !== undefined) {
+            body.postback_template = args.postback_template.trim();
+        }
+        if (apiToken !== undefined)
+            body.api_token = apiToken;
+        if (args.status !== undefined)
+            body.status = args.status;
+        const created = await client.post("/api/traffic-sources", body);
+        // Echo the row the server actually stored (preset templates copied in).
+        // Non-fatal; fall back to the create summary.
+        let stored = null;
+        try {
+            stored = await client.get(`/api/traffic-sources/${encodeURIComponent(created.id)}`);
+        }
+        catch {
+            stored = null;
+        }
+        return textResult([
+            `✅ Traffic source **${mdCell(args.name)}** created (id \`${created.id}\`).`,
+            "",
+            stored
+                ? [
+                    "| Field | Value |",
+                    "|---|---|",
+                    `| Preset | ${stored.preset ? mdCell(stored.preset) : "— (custom)"} |`,
+                    `| Tracking template | ${stored.tracking_template ? mdCell(stored.tracking_template) : "—"} |`,
+                    `| Postback template | ${stored.postback_template ? mdCell(stored.postback_template) : "—"} |`,
+                    `| API token | ${stored.has_api_token ? "set (write-only)" : "—"} |`,
+                    `| Status | ${mdCell(stored.status)} |`,
+                ].join("\n")
+                : summaryTable,
+            ...(warnings.length ? ["", ...warnings] : []),
+            "",
+            "Link zones to it with `create_zone`/`update_zone` `traffic_source_id`; " +
+                "`get_zone_url` then renders its tracking template. Replace any `[BRACKETED]` " +
+                "values in the postback template with your account's, then use it for the " +
+                "zone's postback_url.",
+        ].join("\n"));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+function templateCell(explicit, presetValue, fallback) {
+    if (explicit !== undefined) {
+        return explicit ? mdCell(explicit) : "— _(explicitly empty)_";
+    }
+    if (presetValue)
+        return `${mdCell(presetValue)} _(copied from preset)_`;
+    return fallback;
+}
+async function fetchPreset(client, presetId) {
+    try {
+        const res = await client.get("/api/traffic-source-presets");
+        const presets = res.presets ?? [];
+        const preset = presets.find((p) => p.id.toLowerCase() === presetId.toLowerCase());
+        return preset
+            ? { state: "found", preset }
+            : { state: "unknown", ids: presets.map((p) => p.id) };
+    }
+    catch {
+        return { state: "unavailable" };
+    }
+}
+//# sourceMappingURL=createTrafficSource.js.map

package/dist/tools/createZone.d.ts

@@ -8,6 +8,7 @@ export declare const createZoneInputSchema: {
     site_url: z.ZodOptional<z.ZodString>;
     traffic_back_url: z.ZodOptional<z.ZodString>;
     user_email: z.ZodOptional<z.ZodString>;
+    traffic_source_id: z.ZodOptional<z.ZodString>;
     confirm: z.ZodDefault<z.ZodBoolean>;
 };
 type CreateZoneArgs = {
@@ -16,6 +17,7 @@ type CreateZoneArgs = {
     site_url?: string;
     traffic_back_url?: string;
     user_email?: string;
+    traffic_source_id?: string;
     confirm: boolean;
 };
 export declare function createZone(client: AffsetClient, args: CreateZoneArgs): Promise<CallToolResult>;

package/dist/tools/createZone.js

@@ -4,7 +4,8 @@ import { errorResult, textError, textResult } from "../lib/toolResult.js";
 import { httpUrlError } from "../lib/urls.js";
 export const CREATE_ZONE_DESCRIPTION = "Create a traffic-source zone in the current namespace. Requires a name; optional " +
     "postback_url (where conversions are reported back — include {source_click_id}), " +
-    "site_url, traffic_back_url, and user_email (publisher owner). Status is always " +
+    "site_url, traffic_back_url, user_email (publisher owner), and traffic_source_id " +
+    "(get_zone_url then renders that source's tracking template). Status is always " +
     "active on create. Counts against the plan's zone limit (402 if exceeded). " +
     "DRY-RUN by default; pass confirm=true to apply.";
 export const createZoneInputSchema = {
@@ -26,6 +27,13 @@ export const createZoneInputSchema = {
         .email()
         .optional()
         .describe("Optional publisher email to own this zone (owner/manager only)."),
+    traffic_source_id: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Traffic source to link (see list_traffic_sources). Must be a source in this " +
+        "namespace. get_zone_url/get_tracking_link then render its tracking template."),
     confirm: z
         .boolean()
         .default(false)
@@ -62,6 +70,7 @@ export async function createZone(client, args) {
             `| Site | ${mdCell(args.site_url ?? "—")} |`,
             `| Traffic back | ${mdCell(args.traffic_back_url ?? "—")} |`,
             `| Publisher | ${mdCell(args.user_email ?? "—")} |`,
+            `| Traffic source | ${args.traffic_source_id ? `\`${mdCell(args.traffic_source_id)}\`` : "—"} |`,
         ].join("\n");
         if (!args.confirm) {
             return textResult([
@@ -81,6 +90,8 @@ export async function createZone(client, args) {
             body.traffic_back_url = args.traffic_back_url;
         if (args.user_email !== undefined)
             body.user_email = args.user_email;
+        if (args.traffic_source_id !== undefined)
+            body.traffic_source_id = args.traffic_source_id;
         const created = await client.post("/api/zones", body);
         // Create response is sparse — fetch full row for the echo.
         let zone = null;
@@ -106,6 +117,7 @@ export async function createZone(client, args) {
             `| Site | ${mdCell(zone?.site_url ?? args.site_url ?? "—")} |`,
             `| Traffic back | ${mdCell(zone?.traffic_back_url ?? args.traffic_back_url ?? "—")} |`,
             `| Publisher | ${mdCell(zone?.user_email ?? args.user_email ?? "—")} |`,
+            `| Traffic source | ${zone?.traffic_source_name ? mdCell(zone.traffic_source_name) : args.traffic_source_id ? `\`${mdCell(args.traffic_source_id)}\`` : "—"} |`,
             "",
             "Use this zone id with `create_campaign` (or pass it as zone_id) for tracking links.",
         ].join("\n"));

package/dist/tools/getStats.d.ts

@@ -19,6 +19,7 @@ export declare const getStatsInputSchema: {
     conversion_type: z.ZodOptional<z.ZodString>;
     advertiser_email: z.ZodOptional<z.ZodString>;
     publisher_email: z.ZodOptional<z.ZodString>;
+    paid_only: z.ZodDefault<z.ZodBoolean>;
 };
 type GetStatsArgs = {
     group_by: GroupBy;
@@ -35,6 +36,7 @@ type GetStatsArgs = {
     conversion_type?: string;
     advertiser_email?: string;
     publisher_email?: string;
+    paid_only?: boolean;
 };
 export declare function getStats(client: AffsetClient, args: GetStatsArgs): Promise<CallToolResult>;
 export {};

package/dist/tools/getStats.js

@@ -6,12 +6,15 @@ import { GROUP_BY_VALUES, SUB_KEYS } from "../types.js";
 export const GET_STATS_DESCRIPTION = "Pull affset traffic stats grouped by a single dimension. Returns impressions, clicks, " +
     "conversions, CR, payout, media cost and ROI as a table. Drill down by calling " +
     "repeatedly: first group_by=date or campaign_id, then narrow with filters " +
-    "(campaign_ids, zone_ids, sub1..sub5, conversion_type, advertiser_email, publisher_email) " +
-    "and change group_by (zone_id, sub1, ...). " +
+    "(campaign_ids, zone_ids, sub1..sub5, conversion_type, advertiser_email, publisher_email, " +
+    "paid_only) and change group_by (zone_id, sub1, ...). " +
     'Sub columns are titled with the tenant\'s configured labels (e.g. "Zone (sub1)") ' +
     "when set; group_by/filters always take the raw subN key. " +
     "conversion_type only matches conversion rows, so filtering by it zeroes impressions, clicks " +
     "and media cost — it narrows to conversions of that type, not clicks that led to one. " +
+    "paid_only defaults to true (same as the dashboard): conversions and CR exclude informative " +
+    "pings whose pixel type missed payout_goal_type, so CR is not inflated above 100%. Set " +
+    "false for the raw unfiltered count. " +
     "ROI is blank until traffic cost has been imported for the slice. " +
     "group_by=advertiser_email / publisher_email break down by team member; the API limits them " +
     "to owner/manager plus the matching side's manager role (403 otherwise). " +
@@ -61,15 +64,27 @@ export const getStatsInputSchema = {
         .optional()
         .describe("Narrow to one publisher's zones, independent of group_by. Owner/manager: any publisher. " +
         "publisher_manager: only one of their own assigned publishers (else 403). Other roles: 403."),
+    paid_only: z
+        .boolean()
+        .default(true)
+        .describe("Drop informative conversions (postback_skipped=non_goal_type, e.g. lp_view pings that " +
+        "missed payout_goal_type) from the conversions count and CR. Silent conversions still " +
+        "count — not a payout>0 filter. Default true (matches the dashboard) so CR is not " +
+        "inflated above 100%. Set false for the raw count."),
 };
 export async function getStats(client, args) {
     try {
         const timeZone = await client.getTenantTimezone();
         const { from, to, label } = resolveRange(args.range, args.from, args.to, timeZone);
+        // The API accepts only the literal strings "true"/"false"; omitted = false.
+        // MCP (and the dashboard) default to true so CR isn't inflated by lp_view
+        // pings, so we always send the resolved value rather than omitting it.
+        const paidOnly = args.paid_only ?? true;
         const query = {
             from,
             to,
             group_by: args.group_by,
+            paid_only: String(paidOnly),
         };
         if (args.campaign_ids?.length)
             query.campaign_ids = args.campaign_ids.join(",");
@@ -91,11 +106,12 @@ export async function getStats(client, args) {
         const data = await client.get("/api/stats", query);
         const table = formatStatsTable(data.stats ?? [], args.group_by, data.sub_labels);
         const heading = groupHeader(args.group_by, data.sub_labels);
+        const paidNote = paidOnly ? "" : " (including informative conversions)";
         return {
             content: [
                 {
                     type: "text",
-                    text: `**Stats — ${label}, by ${heading}**\n\n${table}`,
+                    text: `**Stats — ${label}, by ${heading}**${paidNote}\n\n${table}`,
                 },
             ],
         };

package/dist/tools/getTrackingLink.js

@@ -1,15 +1,16 @@
 import { z } from "zod";
 import { AffsetApiError } from "../client.js";
 import { mdCell } from "../lib/format.js";
-import { buildTrackingLink, fetchTenantIntegration, subLegend } from "../lib/integrationUrls.js";
-import { collectSubs, linkInputSchema } from "../lib/linkArgs.js";
+import { buildTrackingLink, 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_TRACKING_LINK_DESCRIPTION = "Get the tracking link for an existing campaign + zone — the /track/click link that goes " +
     "straight to that one campaign with no rotation or targeting checks. Both the campaign " +
     "and zone must be active for the public link to work. Same link create_campaign echoes on " +
     "create; this re-derives it later, for any " +
-    "campaign, with whatever sub values you want. Uses the tenant's custom API domain when " +
+    "campaign, with whatever sub values you want. A zone linked to a traffic source renders " +
+    "that source's tracking template instead. Uses the tenant's custom API domain when " +
     "one is set. Read-only: builds the URL, changes nothing.";
 export const getTrackingLinkInputSchema = {
     campaign_id: z
@@ -45,12 +46,15 @@ export async function getTrackingLink(client, config, args) {
         const { campaign } = campaignResult;
         const { zone, inactiveWarning } = zoneResult;
         const subs = collectSubs(args);
+        const linked = await resolveLinkedSource(client, zone, hasExplicitLinkParams(args));
         const url = buildTrackingLink(integration.baseUrl, campaign.id, zone.id, {
             sourceClickId: args.source_click_id,
             subs,
             cost: args.cost,
             subLabels: integration.subLabels,
+            template: linked.template,
         });
+        const templated = linked.template !== undefined;
         const legend = subLegend(integration.subLabels, subs);
         const statusNote = campaign.status === "active"
             ? "active — serving still depends on dates and budget state; also a /serve candidate"
@@ -67,6 +71,7 @@ export async function getTrackingLink(client, config, args) {
             "",
             "| Field | Value |",
             "|---|---|",
+            ...(linked.sourceLabel ? [`| Traffic source | ${linked.sourceLabel} |`] : []),
             `| Campaign status | ${statusNote} |`,
             `| Offer URL | ${mdCell(campaign.redirect_url ?? "—")} |`,
             `| Zone status | ${zone.status} |`,
@@ -74,13 +79,16 @@ export async function getTrackingLink(client, config, args) {
             ...(legend ? [`| Sub slots | ${legend} |`] : []),
             ...(availabilityWarnings.length ? ["", ...availabilityWarnings] : []),
             ...(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 on the click row here. Use it on this link **or** on a zone URL for the same traffic, never both."
-                : "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),
             "",
             "_Geo and other targeting rules are enforced in /serve rotation only — this link is " +
                 "not geo-gated. Use `get_zone_url` when you want affset to pick the campaign._",
@@ -90,6 +98,15 @@ export async function getTrackingLink(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 on the click row here. Use it on this link **or** on a zone URL for the same traffic, never both.";
+    }
+    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`.";
+}
 function campaignAvailabilityWarnings(campaign) {
     const warnings = [];
     const now = Date.now();

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;