@affset/mcp 0.2.0 → 0.4.0

package/dist/tools/updateTrafficSource.js

@@ -0,0 +1,171 @@
+import { z } from "zod";
+import { AffsetApiError } from "../client.js";
+import { SOURCE_CLICK_ID_PARAM, templateHasParam } from "../lib/integrationUrls.js";
+import { displayValue, renderDiff } from "../lib/patch.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;
+/** Zod: replacement string, or null to clear. */
+const clearableTemplate = z.union([z.string().max(TEMPLATE_MAX), z.null()]);
+export const UPDATE_TRAFFIC_SOURCE_DESCRIPTION = "Update a traffic source (name, tracking_template, postback_template, api_token, " +
+    'status). Partial update — only provided fields change; pass null (or "") to clear a ' +
+    "template or the stored api_token. Zones linked to the source pick the new tracking " +
+    "template up immediately in get_zone_url/get_tracking_link. " +
+    "DRY-RUN by default; pass confirm=true to apply.";
+export const updateTrafficSourceInputSchema = {
+    traffic_source_id: z.string().trim().min(1).describe("Traffic source id to update."),
+    name: z
+        .string()
+        .trim()
+        .min(1)
+        .max(NAME_MAX)
+        .optional()
+        .describe("New display name (unique per tenant)."),
+    tracking_template: clearableTemplate
+        .optional()
+        .describe("New tracking template (query string appended to the zone URL; must not start " +
+        "with ? or &), or null to clear it."),
+    postback_template: clearableTemplate
+        .optional()
+        .describe("New postback template (http(s) URL with our macros), or null to clear it."),
+    api_token: z
+        .union([z.string().max(TOKEN_MAX), z.null()])
+        .optional()
+        .describe('Replacement network API credential (stored write-only), or null/"" to clear the ' +
+        "stored one. Omit to leave it unchanged."),
+    status: z
+        .enum(TRAFFIC_SOURCE_STATUSES)
+        .optional()
+        .describe("active or archived. Archiving keeps the source linked to its zones — deletion is " +
+        "only possible once no zone references it."),
+    confirm: z
+        .boolean()
+        .default(false)
+        .describe("false = dry-run preview (default). true = apply the update."),
+};
+export async function updateTrafficSource(client, args) {
+    try {
+        const patch = buildPatch(args);
+        if ("error" in patch)
+            return textError(patch.error);
+        if (Object.keys(patch.body).length === 0) {
+            return textError("Provide at least one field to update: name, tracking_template, " +
+                "postback_template, api_token, status.");
+        }
+        let existing;
+        try {
+            existing = await client.get(`/api/traffic-sources/${encodeURIComponent(args.traffic_source_id)}`);
+        }
+        catch (err) {
+            if (err instanceof AffsetApiError && err.status === 404) {
+                return textError(`Traffic source \`${args.traffic_source_id}\` not found in this namespace.`);
+            }
+            throw err;
+        }
+        const changes = diffSource(existing, patch.body);
+        if (changes.length === 0) {
+            return textResult(`Nothing to change on traffic source \`${existing.id}\` (${existing.name}) — ` +
+                "provided fields already match current values.");
+        }
+        const warnings = [];
+        const linkedZones = existing.linked_zones ?? 0;
+        if ("tracking_template" in patch.body && linkedZones > 0) {
+            warnings.push(`The new tracking template applies to the ${linkedZones} linked ` +
+                `zone${linkedZones === 1 ? "" : "s"} the next time a URL is rendered — links ` +
+                "already pasted into network campaigns keep their old parameters until replaced.");
+        }
+        if (typeof patch.body.tracking_template === "string" &&
+            patch.body.tracking_template !== "" &&
+            !templateHasParam(patch.body.tracking_template, SOURCE_CLICK_ID_PARAM)) {
+            warnings.push("⚠️ The new tracking template has no `source_click_id=` parameter — the " +
+                "network's click token will not be captured on linked zones' URLs.");
+        }
+        if (patch.body.status === "archived" && existing.status !== "archived") {
+            warnings.push("Archived sources stay linked to their zones and keep rendering their template; " +
+                "archiving only hides the source from active pickers.");
+        }
+        if (!args.confirm) {
+            return textResult([
+                `**Dry run** — would update traffic source \`${existing.id}\` (${existing.name}).`,
+                "",
+                renderDiff(changes),
+                ...(warnings.length ? ["", ...warnings] : []),
+                "",
+                "Call again with `confirm: true` to apply.",
+            ].join("\n"));
+        }
+        const updated = await client.put(`/api/traffic-sources/${encodeURIComponent(args.traffic_source_id)}`, patch.body);
+        return textResult([
+            `✅ Traffic source \`${updated.id}\` updated.`,
+            "",
+            renderDiff(changes),
+            ...(warnings.length ? ["", ...warnings] : []),
+        ].join("\n"));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+function buildPatch(args) {
+    const body = {};
+    if (args.name !== undefined)
+        body.name = args.name;
+    if (args.status !== undefined)
+        body.status = args.status;
+    // Templates clear with "" — the server rejects null for them (api_token is the
+    // one field where null also clears).
+    if (args.tracking_template !== undefined) {
+        const value = args.tracking_template === null ? "" : args.tracking_template.trim();
+        if (value && /^[?&]/.test(value)) {
+            return {
+                error: "tracking_template must not start with ? or & — it is appended after ? automatically.",
+            };
+        }
+        body.tracking_template = value;
+    }
+    if (args.postback_template !== undefined) {
+        const value = args.postback_template === null ? "" : args.postback_template.trim();
+        if (value) {
+            const err = httpUrlError(value, "postback_template");
+            if (err)
+                return { error: err };
+        }
+        body.postback_template = value;
+    }
+    if (args.api_token !== undefined) {
+        body.api_token = args.api_token === null ? null : args.api_token.trim();
+    }
+    return { body };
+}
+/**
+ * api_token never round-trips: the existing row only carries has_api_token, and
+ * the diff must not echo the new value either.
+ */
+function diffSource(existing, body) {
+    const changes = [];
+    for (const [field, to] of Object.entries(body)) {
+        if (field === "api_token") {
+            const from = existing.has_api_token ? "(set)" : "(none)";
+            const toDisplay = to === null || to === "" ? "(cleared)" : "(set — write-only)";
+            if (existing.has_api_token && (to === null || to === "")) {
+                changes.push({ field, from, to: toDisplay });
+            }
+            else if (to !== null && to !== "") {
+                changes.push({ field, from, to: toDisplay });
+            }
+            else if (!existing.has_api_token && (to === null || to === "")) {
+                // Clearing an absent token is a no-op; skip so "nothing to change" stays honest.
+            }
+            continue;
+        }
+        const from = existing[field];
+        if (String(from ?? "") === String(to ?? ""))
+            continue;
+        changes.push({ field, from: displayValue(from ?? null), to: displayValue(to) });
+    }
+    return changes;
+}
+//# sourceMappingURL=updateTrafficSource.js.map

package/dist/tools/updateZone.d.ts

@@ -10,6 +10,7 @@ export declare const updateZoneInputSchema: {
     postback_url: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
     site_url: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
     traffic_back_url: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
+    traffic_source_id: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNull]>>;
     confirm: z.ZodDefault<z.ZodBoolean>;
 };
 type UpdateZoneArgs = {
@@ -19,6 +20,7 @@ type UpdateZoneArgs = {
     postback_url?: string | null;
     site_url?: string | null;
     traffic_back_url?: string | null;
+    traffic_source_id?: string | null;
     confirm: boolean;
 };
 export declare function updateZone(client: AffsetClient, args: UpdateZoneArgs): Promise<CallToolResult>;

package/dist/tools/updateZone.js

@@ -6,8 +6,10 @@ import { httpUrlError } from "../lib/urls.js";
 import { ZONE_STATUSES } from "../types.js";
 /** Zod: optional http(s) URL, or null to clear. */
 const clearableUrl = z.union([z.string().min(1), z.null()]);
-export const UPDATE_ZONE_DESCRIPTION = "Update a traffic-source zone (name, status, postback_url, site_url, traffic_back_url). " +
-    "Partial update — only provided fields change. Pass null for a URL field to clear it. " +
+export const UPDATE_ZONE_DESCRIPTION = "Update a traffic-source zone (name, status, postback_url, site_url, traffic_back_url, " +
+    "traffic_source_id). Partial update — only provided fields change. Pass null for a URL " +
+    "field or traffic_source_id to clear it. Linking a traffic source makes " +
+    "get_zone_url/get_tracking_link render its tracking template. " +
     "DRY-RUN by default; pass confirm=true to apply.";
 export const updateZoneInputSchema = {
     zone_id: z.string().min(1).describe("Zone id to update."),
@@ -18,6 +20,11 @@ export const updateZoneInputSchema = {
         .describe("S2S postback URL, or null to clear. Prefer including {source_click_id}."),
     site_url: clearableUrl.optional().describe("Site URL, or null to clear."),
     traffic_back_url: clearableUrl.optional().describe("Traffic-back URL, or null to clear."),
+    traffic_source_id: z
+        .union([z.string().trim().min(1), z.null()])
+        .optional()
+        .describe("Traffic source to link (see list_traffic_sources; must be in this namespace), " +
+        "or null to unlink."),
     confirm: z
         .boolean()
         .default(false)
@@ -29,7 +36,8 @@ export async function updateZone(client, args) {
         if ("error" in patch)
             return textError(patch.error);
         if (Object.keys(patch.body).length === 0) {
-            return textError("Provide at least one field to update: name, status, postback_url, site_url, traffic_back_url.");
+            return textError("Provide at least one field to update: name, status, postback_url, site_url, " +
+                "traffic_back_url, traffic_source_id.");
         }
         let existing;
         try {
@@ -103,6 +111,8 @@ function buildPatch(args) {
             return { error: err };
         body[key] = args[key];
     }
+    if (args.traffic_source_id !== undefined)
+        body.traffic_source_id = args.traffic_source_id;
     return { body };
 }
 function diffZone(existing, body) {

package/dist/types.d.ts

@@ -111,6 +111,9 @@ export interface Zone {
     postback_url?: string | null;
     user_email?: string | null;
     manager_email?: string | null;
+    /** Linked traffic source; its tracking template drives the URL tools. */
+    traffic_source_id?: string | null;
+    traffic_source_name?: string | null;
     created_at?: number;
     updated_at?: number;
 }
@@ -131,6 +134,101 @@ export interface UpdateCampaignResponse {
     id: number;
     updated_at: number;
 }
+/**
+ * One row from GET /api/traffic-sources. The stored network API credential is
+ * write-only — reads carry `has_api_token`, never the token itself.
+ */
+export interface TrafficSource {
+    id: string;
+    name: string;
+    preset: string | null;
+    tracking_template: string;
+    postback_template: string;
+    has_api_token: boolean;
+    status: string;
+    created_at?: number;
+    updated_at?: number;
+    /** Present on GET /api/traffic-sources/{id} only. */
+    linked_zones?: number;
+}
+export interface TrafficSourcesResponse {
+    traffic_sources: TrafficSource[];
+    pagination: Pagination;
+}
+export interface CreateTrafficSourceResponse {
+    id: string;
+    status: string;
+    created_at: number;
+}
+export interface UpdateTrafficSourceResponse {
+    id: string;
+    updated_at: number;
+}
+/** One entry from GET /api/traffic-source-presets. */
+export interface TrafficSourcePreset {
+    id: string;
+    name: string;
+    doc_url: string;
+    tracking_template: string;
+    postback_template: string;
+    sub_meanings: Partial<Record<SubKey, string>>;
+    notes: string;
+}
+export interface TrafficSourcePresetsResponse {
+    presets: TrafficSourcePreset[];
+}
+/**
+ * One write that entered Affset's mutation stage
+ * (GET /api/traffic-sources/{id}/bid-changes and `last_change` on the bids list).
+ * `changed_by` is the caller's email.
+ */
+export interface SourceBidChange {
+    id: string;
+    source_id: string;
+    network_campaign_id: string;
+    previous_bid: number | null;
+    bid: number;
+    currency: string;
+    pricing_model: string;
+    status: "pending" | "applied" | "failed";
+    error: string | null;
+    changed_by: string;
+    created_at: number;
+}
+/**
+ * One network campaign from GET /api/traffic-sources/{id}/bids — read live from
+ * the network account. `name` and `status_label` are the network's own text.
+ */
+export interface SourceBidCampaign {
+    network_campaign_id: string;
+    name: string;
+    status: "active" | "paused" | "other";
+    status_label: string;
+    bid: number | null;
+    currency: string;
+    pricing_model: string;
+    extra: Record<string, number>;
+    last_change: SourceBidChange | null;
+}
+export interface SourceBidsResponse {
+    campaigns: SourceBidCampaign[];
+    fetched_at: number;
+}
+/** Response of POST /api/traffic-sources/{id}/bids. */
+export interface SetSourceBidResponse {
+    change: SourceBidChange;
+    campaign: {
+        network_campaign_id: string;
+        name: string;
+        status: string;
+        bid: number | null;
+        previous_bid: number | null;
+        currency: string;
+        pricing_model: string;
+    };
+    audit_finalized: boolean;
+    warning?: string;
+}
 /** Subset of GET /api/tenant this server reads. */
 export interface TenantSettingsResponse {
     company?: string;
@@ -206,5 +304,6 @@ export declare const GROUP_BY_VALUES: readonly ["date", "campaign_id", "zone_id"
 export type GroupBy = (typeof GROUP_BY_VALUES)[number];
 export declare const CAMPAIGN_STATUSES: readonly ["active", "paused", "archived"];
 export declare const ZONE_STATUSES: readonly ["active", "inactive"];
+export declare const TRAFFIC_SOURCE_STATUSES: readonly ["active", "archived"];
 export declare const PAYMENT_MODELS: readonly ["cpa", "cpm"];
 export declare const PACING_VALUES: readonly ["asap", "even"];

package/dist/types.js

@@ -14,6 +14,7 @@ export const GROUP_BY_VALUES = [
 ];
 export const CAMPAIGN_STATUSES = ["active", "paused", "archived"];
 export const ZONE_STATUSES = ["active", "inactive"];
+export const TRAFFIC_SOURCE_STATUSES = ["active", "archived"];
 export const PAYMENT_MODELS = ["cpa", "cpm"];
 export const PACING_VALUES = ["asap", "even"];
 //# sourceMappingURL=types.js.map

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * package.json here would break bundlers; a sync test guards the duplicate
  * (see registerTools.test.ts).
  */
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.4.0";

package/dist/version.js

@@ -4,5 +4,5 @@
  * package.json here would break bundlers; a sync test guards the duplicate
  * (see registerTools.test.ts).
  */
-export const VERSION = "0.2.0";
+export const VERSION = "0.4.0";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@affset/mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "mcpName": "io.github.affset/mcp",
   "description": "MCP server for the affset ad platform — stats, campaigns, zones, payouts, targeting, sub labels, and team from your chat client.",
   "type": "module",