@affset/mcp 0.1.1 → 0.3.0

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

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { AffsetClient } from "../client.js";
+export declare const CREATE_ZONE_DESCRIPTION: string;
+export declare const createZoneInputSchema: {
+    name: z.ZodString;
+    postback_url: z.ZodOptional<z.ZodString>;
+    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 = {
+    name: string;
+    postback_url?: string;
+    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>;
+export {};

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/cutZones.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { AffsetClient } from "../client.js";
+import { RANGE_PRESETS } from "../lib/time.js";
+export declare const CUT_ZONES_DESCRIPTION: string;
+export declare const cutZonesInputSchema: {
+    campaign_id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    cr_max: z.ZodOptional<z.ZodNumber>;
+    spend_min: z.ZodOptional<z.ZodNumber>;
+    roi_max: z.ZodOptional<z.ZodNumber>;
+    min_clicks: z.ZodDefault<z.ZodNumber>;
+    range: z.ZodOptional<z.ZodEnum<["today", "yesterday", "last_7_days", "last_30_days", "this_month"]>>;
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+    confirm: z.ZodDefault<z.ZodBoolean>;
+};
+type CutZonesArgs = {
+    campaign_id: string | number;
+    cr_max?: number;
+    spend_min?: number;
+    roi_max?: number;
+    min_clicks: number;
+    range?: (typeof RANGE_PRESETS)[number];
+    from?: string;
+    to?: string;
+    confirm: boolean;
+};
+export declare function cutZones(client: AffsetClient, args: CutZonesArgs): Promise<CallToolResult>;
+export {};

package/dist/tools/deletePayoutRule.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type AffsetClient } from "../client.js";
+export declare const DELETE_PAYOUT_RULE_DESCRIPTION: string;
+export declare const deletePayoutRuleInputSchema: {
+    campaign_id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    zone_id: z.ZodOptional<z.ZodString>;
+    confirm: z.ZodDefault<z.ZodBoolean>;
+};
+type DeletePayoutRuleArgs = {
+    campaign_id: string | number;
+    zone_id?: string;
+    confirm: boolean;
+};
+export declare function deletePayoutRule(client: AffsetClient, args: DeletePayoutRuleArgs): Promise<CallToolResult>;
+export {};

package/dist/tools/getCampaign.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 GET_CAMPAIGN_DESCRIPTION: string;
+export declare const getCampaignInputSchema: {
+    campaign_id: z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>;
+};
+type GetCampaignArgs = {
+    campaign_id: string | number;
+};
+export declare function getCampaign(client: AffsetClient, args: GetCampaignArgs): Promise<CallToolResult>;
+export {};

package/dist/tools/getCampaign.js

@@ -0,0 +1,150 @@
+import { z } from "zod";
+import { AffsetApiError } from "../client.js";
+import { formatInstant } from "../lib/time.js";
+import { mdCell, money, moneyPrecise } from "../lib/format.js";
+import { fetchPayoutRules } from "../lib/payoutRules.js";
+import { fetchTargetingRules, fetchTargetingTypes, UNENFORCED_TYPES } from "../lib/targeting.js";
+import { errorResult, textError, textResult } from "../lib/toolResult.js";
+export const GET_CAMPAIGN_DESCRIPTION = "Get one campaign's full record: every field (including the untruncated offer URL, " +
+    "exact schedule, budgets/pacing, silent-conversions flag, payout goal type) plus its " +
+    "targeting rules and payout rules in one call. `list_campaigns` renders a summary table " +
+    "(offer URL truncated, no dates/pacing/silent) meant for scanning many campaigns; use " +
+    "this when you need one campaign's complete data — e.g. before recreating it as a new " +
+    "campaign, or before editing it with `update_campaign`.";
+export const getCampaignInputSchema = {
+    campaign_id: z
+        .union([
+        z
+            .string()
+            .trim()
+            .regex(/^[1-9]\d*$/, "campaign_id must be a positive integer")
+            .refine((value) => Number.isSafeInteger(Number(value)), "campaign_id is too large"),
+        z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    ])
+        .describe("Campaign id to fetch."),
+};
+export async function getCampaign(client, args) {
+    try {
+        const campaignId = String(args.campaign_id).trim();
+        if (!campaignId)
+            return textError("campaign_id is required.");
+        let campaign;
+        try {
+            campaign = await client.get(`/api/campaigns/${encodeURIComponent(campaignId)}`);
+        }
+        catch (err) {
+            if (err instanceof AffsetApiError && err.status === 404) {
+                return textError(`Campaign \`${campaignId}\` not found in this namespace.`);
+            }
+            throw err;
+        }
+        const [targetingRules, payoutRules, targetingTypes, timeZone] = await Promise.all([
+            fetchTargetingRules(client, campaignId),
+            fetchPayoutRules(client, campaignId),
+            // Names are a nicety; the rule table still works with bare type ids.
+            fetchTargetingTypes(client).catch(() => []),
+            client.getTenantTimezone(),
+        ]);
+        const typeById = new Map(targetingTypes.map((t) => [t.id, t]));
+        const fmt = (ms) => ms == null ? "—" : `${formatInstant(ms, timeZone)} ${mdCell(timeZone)} (${ms} epoch ms)`;
+        const deadTargetingRules = targetingRules.filter((rule) => {
+            const name = typeById.get(rule.targeting_rule_type_id)?.name.toLowerCase();
+            return name !== undefined && UNENFORCED_TYPES[name] !== undefined;
+        });
+        const payoutGoal = campaign.payout_goal_type?.trim();
+        const fields = [
+            "| Field | Value |",
+            "|---|---|",
+            `| Id | ${campaign.id} |`,
+            `| Name | ${mdCell(campaign.name)} |`,
+            `| Status | ${mdCell(campaign.status)} |`,
+            `| Advertiser | ${mdCell(campaign.user_email ?? "—")} |`,
+            `| Offer URL | ${mdCell(campaign.redirect_url ?? "—")} |`,
+            `| Model | ${mdCell(campaign.payment_model ?? "—")} |`,
+            `| Rate | ${campaign.rate != null ? moneyPrecise(campaign.rate) : "—"} |`,
+            `| Start date | ${fmt(campaign.start_date)} |`,
+            `| End date | ${fmt(campaign.end_date)} |`,
+            `| Daily budget | ${money(campaign.daily_budget)} |`,
+            `| Total budget | ${money(campaign.total_budget)} |`,
+            `| Pacing | ${mdCell(campaign.pacing ?? "—")} |`,
+            `| Budget paused | ${formatBudgetPaused(campaign)} |`,
+            `| Silent conversions | ${formatFlag(campaign.silent)} |`,
+            `| Payout goal type | ${payoutGoal ? mdCell(payoutGoal) : "_none — every conversion type gets the resolved payout_"} |`,
+            `| Created | ${fmt(campaign.created_at)} |`,
+            `| Updated | ${fmt(campaign.updated_at)} |`,
+        ];
+        return textResult([
+            `**Campaign** \`${campaign.id}\` — ${mdCell(campaign.name)}`,
+            "",
+            fields.join("\n"),
+            "",
+            `**Targeting rules** (${targetingRules.length})`,
+            "",
+            renderTargetingRules(targetingRules, typeById),
+            ...(deadTargetingRules.length
+                ? ["", ...renderDeadTargetingWarnings(deadTargetingRules, typeById)]
+                : []),
+            "",
+            `**Payout rules** (${payoutRules.length})`,
+            "",
+            renderPayoutRules(payoutRules),
+            "",
+            "_Recreate elsewhere with `create_campaign` + `update_campaign`, then " +
+                "`set_targeting_rule` / `set_payout_rule` for each rule above._",
+            "_Manage this campaign with `update_campaign`, `set_campaign_status`, " +
+                "`set_targeting_rule`, `set_payout_rule`, `set_payout_goal`._",
+        ].join("\n"));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+function formatFlag(value) {
+    if (value == null)
+        return "—";
+    return value ? "yes" : "no";
+}
+function formatBudgetPaused(campaign) {
+    if (campaign.budget_paused == null)
+        return "—";
+    if (!campaign.budget_paused)
+        return "no";
+    const reason = campaign.budget_pause_reason?.trim();
+    return reason ? `yes (${mdCell(reason)})` : "yes (reason unavailable)";
+}
+function renderTargetingRules(rules, typeById) {
+    if (rules.length === 0) {
+        return "_No targeting rules — campaign is unrestricted on /serve._";
+    }
+    const lines = ["| Id | Type | Method | Rule |", "|---|---|---|---|"];
+    for (const r of rules) {
+        const t = typeById.get(r.targeting_rule_type_id);
+        const typeLabel = t
+            ? `${mdCell(t.name)} (${r.targeting_rule_type_id})`
+            : String(r.targeting_rule_type_id);
+        const inert = t && UNENFORCED_TYPES[t.name.toLowerCase()] ? " ⚠️" : "";
+        lines.push(`| ${r.id ?? "—"} | ${typeLabel}${inert} | ${mdCell(r.targeting_method)} | ${mdCell(r.rule)} |`);
+    }
+    return lines.join("\n");
+}
+function renderDeadTargetingWarnings(rules, typeById) {
+    const names = [...new Set(rules.map((rule) => typeById.get(rule.targeting_rule_type_id).name))];
+    return names.map((name) => `⚠️ \`${mdCell(name)}\` — ${UNENFORCED_TYPES[name.toLowerCase()]}. This rule has no effect.`);
+}
+function renderPayoutRules(rules) {
+    if (rules.length === 0) {
+        return "_No payout rules — conversions resolve to $0 until you set one._";
+    }
+    const lines = ["| Scope | Zone | Payout | Rule id |", "|---|---|--:|---|"];
+    for (const r of rules) {
+        const scope = r.zone_id == null ? "global" : "zone";
+        const zone = r.zone_id == null ? "—" : `\`${r.zone_id}\``;
+        lines.push(`| ${scope} | ${zone} | ${moneyPrecise(r.payout)} | \`${r.id}\` |`);
+    }
+    if (!rules.some((rule) => rule.zone_id == null)) {
+        lines.push("");
+        lines.push("_⚠️ No global rule — conversions from any zone without an override resolve to **$0**._");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=getCampaign.js.map

package/dist/tools/getStats.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { AffsetClient } from "../client.js";
+import { RANGE_PRESETS } from "../lib/time.js";
+import { type GroupBy } from "../types.js";
+export declare const GET_STATS_DESCRIPTION: string;
+export declare const getStatsInputSchema: {
+    group_by: z.ZodDefault<z.ZodEnum<["date", "campaign_id", "zone_id", "country", "conversion_type", "publisher_email", "advertiser_email", "sub1", "sub2", "sub3", "sub4", "sub5"]>>;
+    range: z.ZodOptional<z.ZodEnum<["today", "yesterday", "last_7_days", "last_30_days", "this_month"]>>;
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+    campaign_ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    zone_ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    sub1: z.ZodOptional<z.ZodString>;
+    sub2: z.ZodOptional<z.ZodString>;
+    sub3: z.ZodOptional<z.ZodString>;
+    sub4: z.ZodOptional<z.ZodString>;
+    sub5: z.ZodOptional<z.ZodString>;
+    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;
+    range?: (typeof RANGE_PRESETS)[number];
+    from?: string;
+    to?: string;
+    campaign_ids?: string[];
+    zone_ids?: string[];
+    sub1?: string;
+    sub2?: string;
+    sub3?: string;
+    sub4?: string;
+    sub5?: string;
+    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,10 +6,21 @@ 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) 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. " +
-    "ROI is blank until traffic cost has been imported for the slice.";
+    "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). " +
+    "advertiser_email / publisher_email are also standalone filters — narrow every row to one " +
+    "advertiser's campaigns or one publisher's zones regardless of group_by, instead of breaking " +
+    "every user out into its own row. Same role limits as the matching group_by value.";
 export const getStatsInputSchema = {
     group_by: z
         .enum(GROUP_BY_VALUES)
@@ -34,15 +45,46 @@ export const getStatsInputSchema = {
     sub3: z.string().optional().describe("Filter by sub3 value(s)."),
     sub4: z.string().optional().describe("Filter by sub4 value(s)."),
     sub5: z.string().optional().describe("Filter by sub5 value(s)."),
+    conversion_type: z
+        .string()
+        .optional()
+        .describe("Filter by conversion type value(s) (e.g. deposit, register), comma-separated for multiple. " +
+        'Pass "" to select conversions recorded without a type.'),
+    advertiser_email: z
+        .string()
+        .trim()
+        .email()
+        .optional()
+        .describe("Narrow to one advertiser's campaigns, independent of group_by. Owner/manager: any advertiser. " +
+        "advertiser_manager: only one of their own assigned advertisers (else 403). Other roles: 403."),
+    publisher_email: z
+        .string()
+        .trim()
+        .email()
+        .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(",");
@@ -53,14 +95,23 @@ export async function getStats(client, args) {
             if (value !== undefined)
                 query[key] = value;
         }
+        if (args.conversion_type !== undefined)
+            query.conversion_type = args.conversion_type;
+        if (args.advertiser_email !== undefined) {
+            query.advertiser_email = args.advertiser_email.trim();
+        }
+        if (args.publisher_email !== undefined) {
+            query.publisher_email = args.publisher_email.trim();
+        }
         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.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type AffsetClient } from "../client.js";
+import type { Config } from "../runtimeConfig.js";
+import { type LinkArgs } from "../lib/linkArgs.js";
+export declare const GET_TRACKING_LINK_DESCRIPTION: string;
+export declare const getTrackingLinkInputSchema: {
+    source_click_id: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    cost: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    sub1: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    sub2: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    sub3: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    sub4: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    sub5: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    campaign_id: z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>;
+    zone_id: z.ZodOptional<z.ZodString>;
+};
+type GetTrackingLinkArgs = LinkArgs & {
+    campaign_id: string | number;
+    zone_id?: string;
+};
+export declare function getTrackingLink(client: AffsetClient, config: Config, args: GetTrackingLinkArgs): Promise<CallToolResult>;
+export {};