@affset/mcp 0.1.1 → 0.3.0

package/dist/core.js

@@ -0,0 +1,18 @@
+/**
+ * Runtime-agnostic library surface of @affset/mcp (REMOTE-MCP-PRD.md §5.6).
+ *
+ * Everything exported here runs on any fetch-capable runtime (Node ≥22.13,
+ * Cloudflare Workers) — no `process.env`, no `node:` imports. The stdio
+ * entrypoint (`dist/index.js`, the `affset-mcp` bin) layers env-var loading on
+ * top of this; the remote MCP gateway imports this surface directly and
+ * supplies per-grant credentials instead.
+ *
+ * `loadConfig` (env-var parsing) is deliberately NOT exported: it is the
+ * stdio entrypoint's concern, and its signature drags Node types into
+ * consumers.
+ */
+export { registerAffsetTools, } from "./registerTools.js";
+export { AffsetClient, AffsetApiError } from "./client.js";
+export { DOCS_FEEDS, fetchDocsFeed, DocsFetchError } from "./docs.js";
+export { VERSION } from "./version.js";
+//# sourceMappingURL=core.js.map

package/dist/docs.d.ts

@@ -0,0 +1,39 @@
+import { type Config } from "./runtimeConfig.js";
+/**
+ * Fetches the affset documentation feeds that back the MCP documentation
+ * resources. These are static files published by the marketing site
+ * (see lite-adserver-home/scripts/generate-docs.mjs), generated from the same
+ * source as the /docs page, so the resource content never drifts from the docs.
+ *
+ * Fetched at read time — the resource is always the currently published docs,
+ * not a snapshot pinned to this package version. Unlike the tenant API client,
+ * this sends NO credentials: the docs are public, and the docs origin
+ * (AFFSET_DOCS_URL) is deliberately not the API host that holds the API key.
+ */
+/** One published feed: the URI path segment and how it's served. */
+export interface DocsFeed {
+    /** Trailing path on the docs origin, e.g. "api-reference.md". */
+    file: string;
+    mimeType: string;
+}
+export declare const DOCS_FEEDS: {
+    readonly markdown: {
+        readonly file: "api-reference.md";
+        readonly mimeType: "text/markdown";
+    };
+    readonly json: {
+        readonly file: "api-reference.json";
+        readonly mimeType: "application/json";
+    };
+};
+/** Thrown when a docs feed can't be fetched or looks wrong. */
+export declare class DocsFetchError extends Error {
+    constructor(message: string);
+}
+/**
+ * Fetch one docs feed and return its text. Throws {@link DocsFetchError} with an
+ * actionable message on any network error, non-2xx status, HTML SPA fallback,
+ * invalid body, or oversized response — the MCP layer surfaces that to the
+ * caller as the resource read failure.
+ */
+export declare function fetchDocsFeed(config: Config, feed: DocsFeed): Promise<string>;

package/dist/docs.js

@@ -0,0 +1,105 @@
+import { readResponseText, ResponseTooLargeError } from "./lib/readBody.js";
+import { normalizeRuntimeConfig } from "./runtimeConfig.js";
+export const DOCS_FEEDS = {
+    markdown: { file: "api-reference.md", mimeType: "text/markdown" },
+    json: { file: "api-reference.json", mimeType: "application/json" },
+};
+/** A hostile or misconfigured origin shouldn't be able to flood model context. */
+const MAX_DOCS_BYTES = 2_000_000;
+/** Thrown when a docs feed can't be fetched or looks wrong. */
+export class DocsFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DocsFetchError";
+    }
+}
+async function readDocsBody(res, url) {
+    try {
+        return await readResponseText(res, MAX_DOCS_BYTES);
+    }
+    catch (err) {
+        if (err instanceof ResponseTooLargeError) {
+            throw new DocsFetchError(err.kind === "declared"
+                ? `Docs response from ${url} declares Content-Length ${err.size}, over the ${MAX_DOCS_BYTES}-byte limit.`
+                : `Docs response from ${url} exceeded the ${MAX_DOCS_BYTES}-byte limit while streaming.`);
+        }
+        throw err;
+    }
+}
+/** SPA catch-alls often return 200 HTML for missing static feeds — refuse those. */
+function assertNotHtmlShell(text, contentType, url) {
+    const type = (contentType ?? "").toLowerCase();
+    if (type.includes("text/html") || type.includes("application/xhtml")) {
+        throw new DocsFetchError(`Docs fetch for ${url} returned HTML (${contentType ?? "unknown type"}) instead of the documentation feed. ` +
+            `Is the feed deployed at that origin?`);
+    }
+    const head = text.slice(0, 256).trimStart().toLowerCase();
+    if (head.startsWith("<!doctype html") || head.startsWith("<html")) {
+        throw new DocsFetchError(`Docs fetch for ${url} returned an HTML document instead of the documentation feed. ` +
+            `Is the feed deployed at that origin?`);
+    }
+}
+function validateFeedBody(text, feed, url) {
+    if (text.length === 0) {
+        throw new DocsFetchError(`Docs response from ${url} was empty.`);
+    }
+    if (feed.mimeType === "application/json") {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (err) {
+            throw new DocsFetchError(`Docs response from ${url} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new DocsFetchError(`Docs JSON from ${url} must be a top-level object.`);
+        }
+        return;
+    }
+    // Markdown feed: require a heading so we don't accept arbitrary plain text.
+    if (!/^#\s+\S/m.test(text.slice(0, 4_096))) {
+        throw new DocsFetchError(`Docs Markdown from ${url} does not look like the API reference (missing a top-level heading).`);
+    }
+}
+/**
+ * Fetch one docs feed and return its text. Throws {@link DocsFetchError} with an
+ * actionable message on any network error, non-2xx status, HTML SPA fallback,
+ * invalid body, or oversized response — the MCP layer surfaces that to the
+ * caller as the resource read failure.
+ */
+export async function fetchDocsFeed(config, feed) {
+    const runtimeConfig = normalizeRuntimeConfig(config);
+    const url = `${runtimeConfig.docsBaseUrl}/${feed.file}`;
+    let res;
+    try {
+        res = await fetch(url, {
+            // No Authorization / X-Namespace: the docs are public and this is a
+            // different origin from the tenant API. Accept nudges the CDN toward the
+            // right representation without depending on it.
+            headers: { Accept: feed.mimeType },
+            // Don't follow redirects to a different host — a misconfigured docs
+            // origin shouldn't silently pull content from elsewhere.
+            redirect: "manual",
+            signal: AbortSignal.timeout(runtimeConfig.requestTimeoutMs),
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "TimeoutError") {
+            throw new DocsFetchError(`Timed out after ${runtimeConfig.requestTimeoutMs}ms fetching docs from ${url}`);
+        }
+        throw new DocsFetchError(`Could not reach docs at ${url}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (res.status >= 300 && res.status < 400) {
+        const location = res.headers.get("location") ?? "(no Location header)";
+        throw new DocsFetchError(`Docs fetch for ${url} returned HTTP ${res.status} redirect to ${location}. ` +
+            `AFFSET_DOCS_URL must point at the origin that serves the feeds directly.`);
+    }
+    if (!res.ok) {
+        throw new DocsFetchError(`Docs fetch for ${url} returned HTTP ${res.status}.`);
+    }
+    const text = await readDocsBody(res, url);
+    assertNotHtmlShell(text, res.headers.get("content-type"), url);
+    validateFeedBody(text, feed, url);
+    return text;
+}
+//# sourceMappingURL=docs.js.map

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/lib/format.d.ts

@@ -0,0 +1,46 @@
+import { type GroupBy, type StatRow, type SubLabels } from "../types.js";
+/**
+ * Escape a value for a Markdown table cell. Pipes/newlines break table layout;
+ * backticks and brackets are escaped too since these cells often carry
+ * traffic-source-controlled strings (zone names, sub values) rendered straight
+ * into the model's context — unescaped backticks let that data break out of its
+ * cell and forge what reads like a fenced code block or inline instruction.
+ */
+export declare function mdCell(value: string): string;
+/**
+ * Truncate a value that came from outside the tenant's own dashboard — sub values,
+ * zone/campaign names on rows the API returned, conversion payloads — before it
+ * reaches the model's context. These fields round-trip through public, unauthenticated
+ * endpoints (a click, a conversion pixel), so nothing bounds their length or content
+ * on the way in; without a cap here, one long field could bury an injected
+ * instruction past whatever a client renders or a reviewer reads.
+ */
+export declare function capUntrusted(value: string, max?: number): string;
+/** Format a number as USD, e.g. 1234.5 -> "$1,234.50". */
+export declare function money(n: number | undefined | null): string;
+/**
+ * Format a USD amount that can be smaller than a cent. Payout rules accept down
+ * to $0.00001 and push/mVAS payouts really do sit there, where `money()`'s two
+ * decimals would render $0.005 as "$0.00" — a preview the operator would confirm
+ * believing it said something else. Ordinary amounts still show two decimals.
+ */
+export declare function moneyPrecise(n: number | undefined | null): string;
+/** Format a fraction as a percentage, e.g. 0.0145 -> "1.45%". */
+export declare function pct(fraction: number): string;
+/** Format ROI (a fraction) with sign, e.g. 0.35 -> "+35%". Null -> "—". */
+export declare function roi(fraction: number | null | undefined): string;
+/** Conversion rate for a row (conversions / clicks), 0 when no clicks. */
+export declare function conversionRate(row: StatRow): number;
+/** The human label for a row given the grouping dimension. */
+export declare function rowLabel(row: StatRow, groupBy: GroupBy): string;
+/**
+ * Column title for a grouping: for sub1..sub5 the tenant's label (from the stats
+ * response `sub_labels`) with the raw key appended for addressability —
+ * "Zone (sub1)" — since filters/group_by still take the raw key. Raw key otherwise.
+ */
+export declare function groupHeader(groupBy: GroupBy, subLabels?: SubLabels): string;
+/**
+ * Render grouped stats as a Markdown table with a totals row. CR is derived
+ * client-side; ROI comes from the API (blank until media_cost is populated).
+ */
+export declare function formatStatsTable(rows: StatRow[], groupBy: GroupBy, subLabels?: SubLabels): string;

package/dist/lib/format.js

@@ -77,6 +77,8 @@ export function rowLabel(row, groupBy) {
             return capUntrusted(row.conversion_type || "(none)");
         case "publisher_email":
             return row.publisher_email || "(none)";
+        case "advertiser_email":
+            return row.advertiser_email || "(none)";
         default:
             // sub1..sub5 — attributed from click/pixel query params, same trust level.
             return capUntrusted(row[groupBy] || "(none)");
@@ -89,6 +91,7 @@ const HEADER_BY_GROUP = {
     country: "Country",
     conversion_type: "Conv. type",
     publisher_email: "Publisher",
+    advertiser_email: "Advertiser",
     sub1: "sub1",
     sub2: "sub2",
     sub3: "sub3",

package/dist/lib/integrationUrls.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The two URLs a media buyer hands to a traffic source, and the base they hang off.
+ *
+ * - **Zone URL** — `/serve/{zone_id}`. The network sends traffic here and affset
+ *   picks a campaign out of the zone's rotation (active campaigns only).
+ * - **Tracking link** — `/track/click/{campaign_id}/{zone_id}`. Straight to one
+ *   campaign, no rotation and no targeting checks. The campaign and zone still have
+ *   to be active because the public tracking path reads the active-serving cache.
+ *
+ * Both carry the same query convention: `source_click_id` (the network's own click
+ * token, echoed back on postback) plus the five analytics sub slots.
+ */
+import type { AffsetClient } from "../client.js";
+import type { Config } from "../runtimeConfig.js";
+import { type SubKey, type SubLabels, type Zone } from "../types.js";
+/** Query parameter carrying the traffic source's click token. */
+export declare const SOURCE_CLICK_ID_PARAM = "source_click_id";
+/**
+ * Generic click-token placeholder for zones with no linked traffic source — the
+ * buyer swaps in their network's macro (`[CLICK_ID]`, `${SUBID}`, …). A linked
+ * source replaces the whole query with its own tracking template instead.
+ */
+export declare const DEFAULT_SOURCE_CLICK_ID = "{clickid}";
+export type SubValues = Partial<Record<SubKey, string>>;
+/** Everything needed to build integration URLs, from a single `/api/tenant` read. */
+export interface TenantIntegration {
+    /** Origin the network will actually be pointed at (custom API domain when set). */
+    baseUrl: string;
+    subLabels: SubLabels;
+}
+/**
+ * Resolve the origin for URLs that leave the building. A tenant with a custom API
+ * domain must see that domain: these URLs get pasted into a network's campaign
+ * settings, so they have to be the final ones.
+ *
+ * Never fails — the links matter more than the branding, so a bad or unreadable
+ * setting falls back to the configured API base.
+ */
+export declare function fetchTenantIntegration(client: AffsetClient, config: Config): Promise<TenantIntegration>;
+/** `custom_api_domain` is tenant-editable free text — only use it if it parses. */
+export declare function integrationBaseUrl(customApiDomain: string | null | undefined, fallback: string): string;
+export interface LinkParams {
+    /** Click-token macro. Omit for the generic default; pass "" to leave it out. */
+    sourceClickId?: string;
+    /** Explicit sub values; unset slots fall back to a label-derived placeholder. */
+    subs?: SubValues;
+    /** Network cost macro for `?cost=`. Omitted when absent. */
+    cost?: string;
+    subLabels?: SubLabels;
+    /**
+     * A linked traffic source's tracking template: the entire query string, used
+     * verbatim so network macro syntaxes (`{x}`, `${X}`, `##X##`, `[X]`) survive
+     * byte-exact. When set and non-empty, every per-field param above is ignored.
+     */
+    template?: string;
+}
+/** `/serve/{zone_id}` — the zone URL, for campaign rotation. */
+export declare function buildZoneUrl(baseUrl: string, zoneId: string, params?: LinkParams): string;
+/** `/track/click/{campaign_id}/{zone_id}` — straight to one campaign. */
+export declare function buildTrackingLink(baseUrl: string, campaignId: number | string, zoneId: string, params?: LinkParams): string;
+/**
+ * True only when the template contains the exact query-parameter name.
+ * Leading `?`/`&` and per-part whitespace are ignored so a stored template
+ * like `" source_click_id={x}"` still counts (create/update trim, but rows
+ * written from the dashboard may not).
+ */
+export declare function templateHasParam(template: string | undefined, param: string): boolean;
+/** "Creative name" -> `creative_name`; falls back to the raw sub key. */
+export declare function placeholderName(key: string, label: string | undefined): string;
+/** "sub1 = Creative, sub2 = Placement" — so the buyer can see what belongs where. */
+export declare function subLegend(subLabels: SubLabels, subs?: SubValues): string | null;
+/** What the URL tools need to render a linked source's template — or explain why not. */
+export interface LinkedSourceContext {
+    /** Query string for the URL builder, verbatim; undefined → generic assembly. */
+    template?: string;
+    /** "Traffic source" table-row value; undefined when the zone is unlinked. */
+    sourceLabel?: string;
+    /** Warnings and suggestions to append under the URL table. */
+    notes: string[];
+}
+/**
+ * Resolve a zone's linked traffic source into URL-building context (PRD
+ * traffic-sources §4.3). Explicit link params always win over the stored
+ * template — that override is deliberate — and a linked-but-unreadable source
+ * degrades to the generic assembly with a warning instead of failing the tool.
+ */
+export declare function resolveLinkedSource(client: AffsetClient, zone: Pick<Zone, "traffic_source_id" | "traffic_source_name" | "postback_url">, hasManualParams: boolean): Promise<LinkedSourceContext>;

package/dist/lib/integrationUrls.js

@@ -10,13 +10,14 @@
  * Both carry the same query convention: `source_click_id` (the network's own click
  * token, echoed back on postback) plus the five analytics sub slots.
  */
-import { SUB_KEYS } from "../types.js";
+import { SUB_KEYS, } from "../types.js";
 import { mdCell } from "./format.js";
 /** Query parameter carrying the traffic source's click token. */
 export const SOURCE_CLICK_ID_PARAM = "source_click_id";
 /**
- * Default click-token macro. RichAds' spelling — the pilot source; other networks
- * substitute their own (`[CLICK_ID]`, `${SUBID}`, …).
+ * Generic click-token placeholder for zones with no linked traffic source — the
+ * buyer swaps in their network's macro (`[CLICK_ID]`, `${SUBID}`, …). A linked
+ * source replaces the whole query with its own tracking template instead.
  */
 export const DEFAULT_SOURCE_CLICK_ID = "{clickid}";
 /**
@@ -89,7 +90,11 @@ export function buildTrackingLink(baseUrl, campaignId, zoneId, params = {}) {
  * read as the primary parameter in the copied URL. All five sub slots are emitted as
  * a template for the buyer to fill in or delete.
  */
-function withQuery(base, { sourceClickId = DEFAULT_SOURCE_CLICK_ID, subs = {}, cost, subLabels = {} }) {
+function withQuery(base, params) {
+    const template = params.template;
+    if (template?.trim())
+        return `${base}?${template}`;
+    const { sourceClickId = DEFAULT_SOURCE_CLICK_ID, subs = {}, cost, subLabels = {} } = params;
     const parts = [];
     const clickId = sourceClickId.trim();
     if (clickId)
@@ -103,6 +108,16 @@ function withQuery(base, { sourceClickId = DEFAULT_SOURCE_CLICK_ID, subs = {}, c
         parts.push(`cost=${costMacro}`);
     return parts.length > 0 ? `${base}?${parts.join("&")}` : base;
 }
+/**
+ * True only when the template contains the exact query-parameter name.
+ * Leading `?`/`&` and per-part whitespace are ignored so a stored template
+ * like `" source_click_id={x}"` still counts (create/update trim, but rows
+ * written from the dashboard may not).
+ */
+export function templateHasParam(template, param) {
+    const query = (template ?? "").trim().replace(/^[?&]+/, "");
+    return query.split("&").some((part) => part.trim().startsWith(`${param}=`));
+}
 /** "Creative name" -> `creative_name`; falls back to the raw sub key. */
 export function placeholderName(key, label) {
     const slug = (label ?? "")
@@ -125,4 +140,69 @@ export function subLegend(subLabels, subs = {}) {
     });
     return labelled.length > 0 ? labelled.join(" · ") : null;
 }
+/**
+ * Resolve a zone's linked traffic source into URL-building context (PRD
+ * traffic-sources §4.3). Explicit link params always win over the stored
+ * template — that override is deliberate — and a linked-but-unreadable source
+ * degrades to the generic assembly with a warning instead of failing the tool.
+ */
+export async function resolveLinkedSource(client, zone, hasManualParams) {
+    const notes = [];
+    const linkedId = zone.traffic_source_id?.trim();
+    if (!linkedId)
+        return { notes };
+    let source = null;
+    try {
+        source = await client.get(`/api/traffic-sources/${encodeURIComponent(linkedId)}`);
+    }
+    catch {
+        source = null;
+    }
+    if (!source) {
+        const name = mdCell(zone.traffic_source_name ?? linkedId);
+        return {
+            sourceLabel: name,
+            notes: [
+                `⚠️ This zone links to traffic source **${name}**, but it could not be read — ` +
+                    "showing generic placeholders instead of its tracking template.",
+            ],
+        };
+    }
+    const sourceLabel = source.preset
+        ? `${mdCell(source.name)} (preset \`${mdCell(source.preset)}\`)`
+        : mdCell(source.name);
+    if (source.status === "archived") {
+        notes.push(`The linked source **${sourceLabel}** is archived — its template still renders, ` +
+            "but consider relinking the zone if this account is no longer bought from.");
+    }
+    // Prefill suggestion only — never auto-applied: [BRACKETED] account-specific
+    // values have to be filled in by the buyer first.
+    if (!zone.postback_url && source.postback_template) {
+        notes.push(source.postback_template.includes("`")
+            ? `The linked source has a postback template for this zone's postback_url, but it contains backticks — read it with \`list_traffic_sources\`.`
+            : `The linked source suggests a postback URL for this zone — replace \`[BRACKETED]\` account values, then set it with \`update_zone\`: \`${source.postback_template}\``);
+    }
+    if (hasManualParams) {
+        notes.push(`Explicit link parameters override the tracking template of **${sourceLabel}**.`);
+        return { sourceLabel, notes };
+    }
+    const template = source.tracking_template ?? "";
+    if (!template.trim()) {
+        notes.push(`Traffic source **${sourceLabel}** has no tracking template — showing generic ` +
+            "placeholders. Add one with `update_traffic_source`.");
+        return { sourceLabel, notes };
+    }
+    // A backtick cannot be rendered into the fenced URL block without letting the
+    // stored template break out of it; no network macro needs one.
+    if (template.includes("`")) {
+        notes.push(`⚠️ The tracking template of **${sourceLabel}** contains a backtick and was not ` +
+            "rendered — fix the template with `update_traffic_source`.");
+        return { sourceLabel, notes };
+    }
+    if (!templateHasParam(template, SOURCE_CLICK_ID_PARAM)) {
+        notes.push(`⚠️ The source's tracking template has no \`${SOURCE_CLICK_ID_PARAM}=\` parameter — ` +
+            "the network's click token is not captured, so postbacks cannot echo it back.");
+    }
+    return { template, sourceLabel, notes };
+}
 //# sourceMappingURL=integrationUrls.js.map

package/dist/lib/linkArgs.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Input shape shared by the two integration-URL tools. Both hand a URL to a traffic
+ * source, so both take the same knobs: which click-token macro to use, what to put
+ * in the five sub slots, and whether to import the network's cost macro.
+ */
+import { z } from "zod";
+import { type SubValues } from "./integrationUrls.js";
+export declare const linkInputSchema: {
+    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>>;
+};
+export type LinkArgs = {
+    source_click_id?: string;
+    cost?: string;
+    sub1?: string;
+    sub2?: string;
+    sub3?: string;
+    sub4?: string;
+    sub5?: string;
+};
+/** Pull the flat sub1..sub5 args into the record the URL builders take. */
+export declare function collectSubs(args: LinkArgs): SubValues;
+/**
+ * True when the caller passed any link knob explicitly. That is the deliberate
+ * override that beats a linked traffic source's stored tracking template.
+ */
+export declare function hasExplicitLinkParams(args: LinkArgs): boolean;

package/dist/lib/linkArgs.js

@@ -27,9 +27,11 @@ const subSchema = (key) => linkValue(key)
 export const linkInputSchema = {
     source_click_id: linkValue("source_click_id")
         .optional()
-        .describe("The traffic source's click-token macro, e.g. `{clickid}` (RichAds), `[CLICK_ID]`, " +
-        `\`\${SUBID}\`. Default \`${DEFAULT_SOURCE_CLICK_ID}\`. This is what conversion ` +
-        'postbacks echo back via {source_click_id} — pass "" only to omit it deliberately.'),
+        .describe("The traffic source's click-token macro, e.g. `[CLICK_ID]` (RichAds), " +
+        `\`\${SUBID}\` (PropellerAds). Default \`${DEFAULT_SOURCE_CLICK_ID}\`. This is what ` +
+        'conversion postbacks echo back via {source_click_id} — pass "" only to omit it ' +
+        "deliberately. Zones linked to a traffic source render the source's tracking " +
+        "template instead; passing any explicit link parameter overrides that template."),
     cost: linkValue("cost")
         .optional()
         .describe("The network's cost macro, e.g. `{cost}`. Adds `&cost=…` so media cost is imported " +
@@ -50,4 +52,13 @@ export function collectSubs(args) {
     }
     return subs;
 }
+/**
+ * True when the caller passed any link knob explicitly. That is the deliberate
+ * override that beats a linked traffic source's stored tracking template.
+ */
+export function hasExplicitLinkParams(args) {
+    return (args.source_click_id !== undefined ||
+        args.cost !== undefined ||
+        SUB_KEYS.some((key) => args[key] !== undefined));
+}
 //# sourceMappingURL=linkArgs.js.map

package/dist/lib/patch.d.ts

@@ -0,0 +1,10 @@
+/** One field change for dry-run / apply summaries. */
+export interface FieldChange {
+    field: string;
+    from: string;
+    to: string;
+}
+/** Render a before → after markdown table. */
+export declare function renderDiff(changes: FieldChange[]): string;
+/** Display helper for nullable / missing values. */
+export declare function displayValue(value: unknown): string;

package/dist/lib/payoutRules.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Payout-rule helpers shared by the payout tools.
+ *
+ * The API has no update for a payout rule: the (campaign, zone) pair is unique,
+ * so a create over an existing scope returns 409 and changing a payout means
+ * delete-then-create. That leaves a window where the campaign has no rule at all,
+ * and a campaign with no matching rule resolves every conversion to $0 — silently,
+ * because a missing payout is a normal state rather than an error. `replacePayout`
+ * exists so that window is always either closed or reported.
+ */
+import { type AffsetClient } from "../client.js";
+import type { PayoutRule } from "../types.js";
+export declare function fetchPayoutRules(client: AffsetClient, campaignId: string): Promise<PayoutRule[]>;
+/** The rule governing one scope: `null` zoneId is the campaign-wide rule. */
+export declare function findPayoutRule(rules: PayoutRule[], zoneId: string | null): PayoutRule | undefined;
+/** Delete the rule governing one scope (`null` zoneId = the campaign-wide rule). */
+export declare function deletePayoutScope(client: AffsetClient, campaignId: string, zoneId: string | null): Promise<void>;
+export declare function createPayoutRule(client: AffsetClient, campaignId: string, zoneId: string | null, payout: number): Promise<PayoutRule>;
+export type ReplaceResult = {
+    rule: PayoutRule;
+}
+/** Create failed; the previous payout was put back, so nothing was lost. */
+ | {
+    rolledBack: PayoutRule;
+    cause: unknown;
+}
+/** Create failed and the rollback failed too — the scope now has no rule. */
+ | {
+    lost: PayoutRule;
+    cause: unknown;
+    rollbackCause: unknown;
+};
+/**
+ * Replace the payout for one scope. On a failed create the previous rule is
+ * restored, so a network blip or a rejected value cannot leave the campaign
+ * paying $0 on every conversion.
+ */
+export declare function replacePayout(client: AffsetClient, campaignId: string, zoneId: string | null, existing: PayoutRule, payout: number): Promise<ReplaceResult>;

package/dist/lib/readBody.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Bound upstream memory use before parsing or rendering into model context.
+ * Runtime-agnostic (no `node:` imports) so the tenant API client and docs
+ * fetcher can share it on Workers.
+ */
+export declare class ResponseTooLargeError extends Error {
+    readonly kind: "declared" | "streaming";
+    readonly limit: number;
+    readonly size?: number | undefined;
+    readonly name = "ResponseTooLargeError";
+    constructor(kind: "declared" | "streaming", limit: number, size?: number | undefined);
+}
+/**
+ * Read a response body as UTF-8, aborting once it exceeds `maxBytes`. Prefers
+ * Content-Length when present so oversized bodies never enter memory.
+ */
+export declare function readResponseText(res: Response, maxBytes: number): Promise<string>;

package/dist/lib/readBody.js

@@ -0,0 +1,69 @@
+/**
+ * Bound upstream memory use before parsing or rendering into model context.
+ * Runtime-agnostic (no `node:` imports) so the tenant API client and docs
+ * fetcher can share it on Workers.
+ */
+export class ResponseTooLargeError extends Error {
+    kind;
+    limit;
+    size;
+    name = "ResponseTooLargeError";
+    constructor(kind, limit, size) {
+        super(kind === "declared"
+            ? `declared ${size} bytes (limit ${limit})`
+            : `exceeded ${limit} bytes while streaming`);
+        this.kind = kind;
+        this.limit = limit;
+        this.size = size;
+    }
+}
+/**
+ * Read a response body as UTF-8, aborting once it exceeds `maxBytes`. Prefers
+ * Content-Length when present so oversized bodies never enter memory.
+ */
+export async function readResponseText(res, maxBytes) {
+    const contentLength = res.headers.get("content-length");
+    if (contentLength !== null) {
+        const declared = Number(contentLength);
+        if (Number.isFinite(declared) && declared > maxBytes) {
+            if (res.body)
+                await res.body.cancel().catch(() => undefined);
+            throw new ResponseTooLargeError("declared", maxBytes, declared);
+        }
+    }
+    if (!res.body)
+        return "";
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                throw new ResponseTooLargeError("streaming", maxBytes, total);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // cancel() already released the lock; a throw here would mask the
+            // size-limit error the caller needs to surface.
+        }
+    }
+    const body = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(body);
+}
+//# sourceMappingURL=readBody.js.map