@affset/mcp 0.1.0

package/dist/lib/format.js

@@ -0,0 +1,148 @@
+import { SUB_KEYS } 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 function mdCell(value) {
+    return value
+        .replace(/\|/g, "\\|")
+        .replace(/`/g, "\\`")
+        .replace(/\[/g, "\\[")
+        .replace(/\r?\n/g, " ")
+        .trim();
+}
+const DEFAULT_UNTRUSTED_CAP = 500;
+/**
+ * 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 function capUntrusted(value, max = DEFAULT_UNTRUSTED_CAP) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max)}…[truncated ${value.length - max} chars]`;
+}
+/** Format a number as USD, e.g. 1234.5 -> "$1,234.50". */
+export function money(n) {
+    if (n === undefined || n === null)
+        return "—";
+    return `$${n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+/**
+ * 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 function moneyPrecise(n) {
+    if (n === undefined || n === null)
+        return "—";
+    return `$${n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 5 })}`;
+}
+/** Format a fraction as a percentage, e.g. 0.0145 -> "1.45%". */
+export function pct(fraction) {
+    return `${(fraction * 100).toFixed(2)}%`;
+}
+/** Format ROI (a fraction) with sign, e.g. 0.35 -> "+35%". Null -> "—". */
+export function roi(fraction) {
+    if (fraction === undefined || fraction === null)
+        return "—";
+    const sign = fraction >= 0 ? "+" : "";
+    return `${sign}${(fraction * 100).toFixed(0)}%`;
+}
+/** Conversion rate for a row (conversions / clicks), 0 when no clicks. */
+export function conversionRate(row) {
+    return row.clicks > 0 ? row.conversions / row.clicks : 0;
+}
+/** The human label for a row given the grouping dimension. */
+export function rowLabel(row, groupBy) {
+    switch (groupBy) {
+        case "date":
+            return row.date ?? "—";
+        case "campaign_id":
+            return row.campaign_name ?? row.campaign_id ?? "—";
+        case "zone_id":
+            return row.zone_name ?? row.zone_id ?? "—";
+        case "country":
+            return row.country || "(none)";
+        case "conversion_type":
+            // From the conversion pixel's `type=` query param — a public, unauthenticated
+            // endpoint, so this is attacker-controlled free text, not a tenant setting.
+            return capUntrusted(row.conversion_type || "(none)");
+        case "publisher_email":
+            return row.publisher_email || "(none)";
+        default:
+            // sub1..sub5 — attributed from click/pixel query params, same trust level.
+            return capUntrusted(row[groupBy] || "(none)");
+    }
+}
+const HEADER_BY_GROUP = {
+    date: "Date",
+    campaign_id: "Campaign",
+    zone_id: "Zone",
+    country: "Country",
+    conversion_type: "Conv. type",
+    publisher_email: "Publisher",
+    sub1: "sub1",
+    sub2: "sub2",
+    sub3: "sub3",
+    sub4: "sub4",
+    sub5: "sub5",
+};
+/**
+ * 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 function groupHeader(groupBy, subLabels) {
+    if (SUB_KEYS.includes(groupBy)) {
+        const label = subLabels?.[groupBy]?.trim();
+        if (label)
+            return `${label} (${groupBy})`;
+    }
+    return HEADER_BY_GROUP[groupBy];
+}
+/**
+ * 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 function formatStatsTable(rows, groupBy, subLabels) {
+    if (rows.length === 0)
+        return "_No data for this period._";
+    const header = groupHeader(groupBy, subLabels);
+    const lines = [
+        `| ${header} | Impr | Clicks | Conv | CR | Payout | Cost | ROI |`,
+        "|---|--:|--:|--:|--:|--:|--:|--:|",
+    ];
+    let tImpr = 0;
+    let tClicks = 0;
+    let tConv = 0;
+    let tPayout = 0;
+    let tCost = 0;
+    let anyCost = false;
+    for (const row of rows) {
+        tImpr += row.impressions ?? 0;
+        tClicks += row.clicks;
+        tConv += row.conversions;
+        tPayout += row.payout ?? 0;
+        tCost += row.media_cost ?? 0;
+        if ((row.media_cost ?? 0) > 0)
+            anyCost = true;
+        lines.push(`| ${mdCell(rowLabel(row, groupBy))} | ${row.impressions ?? 0} | ${row.clicks} | ${row.conversions} | ${pct(conversionRate(row))} | ${money(row.payout)} | ${money(row.media_cost)} | ${roi(row.roi)} |`);
+    }
+    const totalCr = tClicks > 0 ? tConv / tClicks : 0;
+    const totalRoi = anyCost && tCost > 0 ? (tPayout - tCost) / tCost : null;
+    lines.push(`| **Total** | **${tImpr}** | **${tClicks}** | **${tConv}** | **${pct(totalCr)}** | **${money(tPayout)}** | **${money(tCost)}** | **${roi(totalRoi)}** |`);
+    if (!anyCost) {
+        lines.push("");
+        lines.push("_Cost/ROI are blank — media_cost not populated for this slice._");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=format.js.map

package/dist/lib/integrationUrls.js

@@ -0,0 +1,128 @@
+/**
+ * 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 { 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}`, …).
+ */
+export const DEFAULT_SOURCE_CLICK_ID = "{clickid}";
+/**
+ * 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 async function fetchTenantIntegration(client, config) {
+    try {
+        const settings = await client.get("/api/tenant");
+        return {
+            baseUrl: integrationBaseUrl(settings.custom_api_domain, config.baseUrl),
+            subLabels: settings.sub_labels ?? {},
+        };
+    }
+    catch {
+        return { baseUrl: stripTrailingSlash(config.baseUrl), subLabels: {} };
+    }
+}
+/** `custom_api_domain` is tenant-editable free text — only use it if it parses. */
+export function integrationBaseUrl(customApiDomain, fallback) {
+    const domain = customApiDomain?.trim();
+    if (!domain)
+        return stripTrailingSlash(fallback);
+    // A non-http scheme has to be rejected, not papered over: prefixing "https://"
+    // onto "ftp://files.example.com" parses as host "ftp" with the rest as the path,
+    // which would silently hand the network "https://ftp".
+    const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(domain)?.[1]?.toLowerCase();
+    if (scheme && scheme !== "http" && scheme !== "https") {
+        return stripTrailingSlash(fallback);
+    }
+    try {
+        const parsed = new URL(scheme ? domain : `https://${domain}`);
+        if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+            parsed.username ||
+            parsed.password ||
+            (parsed.pathname !== "/" && parsed.pathname !== "") ||
+            parsed.search ||
+            parsed.hash) {
+            return stripTrailingSlash(fallback);
+        }
+        return stripTrailingSlash(parsed.origin);
+    }
+    catch {
+        return stripTrailingSlash(fallback);
+    }
+}
+function stripTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+/** `/serve/{zone_id}` — the zone URL, for campaign rotation. */
+export function buildZoneUrl(baseUrl, zoneId, params = {}) {
+    return withQuery(`${stripTrailingSlash(baseUrl)}/serve/${encodeURIComponent(zoneId)}`, params);
+}
+/** `/track/click/{campaign_id}/{zone_id}` — straight to one campaign. */
+export function buildTrackingLink(baseUrl, campaignId, zoneId, params = {}) {
+    const path = `/track/click/${encodeURIComponent(String(campaignId))}/${encodeURIComponent(zoneId)}`;
+    return withQuery(`${stripTrailingSlash(baseUrl)}${path}`, params);
+}
+/**
+ * Values go in verbatim, not percent-encoded: what these carry are the traffic
+ * source's own macros (`{clickid}`, `[CLICK_ID]`, `${SUBID}`), which the source
+ * expands before the request ever reaches affset. Encoding them would hand the
+ * network a URL it cannot substitute into.
+ *
+ * `source_click_id` leads — it is what conversion postbacks depend on, so it should
+ * 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 = {} }) {
+    const parts = [];
+    const clickId = sourceClickId.trim();
+    if (clickId)
+        parts.push(`${SOURCE_CLICK_ID_PARAM}=${clickId}`);
+    for (const key of SUB_KEYS) {
+        const explicit = subs[key]?.trim();
+        parts.push(`${key}=${explicit || `{${placeholderName(key, subLabels[key])}}`}`);
+    }
+    const costMacro = cost?.trim();
+    if (costMacro)
+        parts.push(`cost=${costMacro}`);
+    return parts.length > 0 ? `${base}?${parts.join("&")}` : base;
+}
+/** "Creative name" -> `creative_name`; falls back to the raw sub key. */
+export function placeholderName(key, label) {
+    const slug = (label ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "_")
+        .replace(/[^a-z0-9_-]/g, "");
+    return slug || key;
+}
+/** "sub1 = Creative, sub2 = Placement" — so the buyer can see what belongs where. */
+export function subLegend(subLabels, subs = {}) {
+    const labelled = SUB_KEYS.flatMap((key) => {
+        const value = subs[key]?.trim();
+        const label = subLabels[key]?.trim();
+        if (!value && !label)
+            return [];
+        return value
+            ? [`\`${key}\` = ${mdCell(value)}${label ? ` (${mdCell(label)})` : ""}`]
+            : [`\`${key}\` = ${mdCell(label)}`];
+    });
+    return labelled.length > 0 ? labelled.join(" · ") : null;
+}
+//# sourceMappingURL=integrationUrls.js.map

package/dist/lib/linkArgs.js

@@ -0,0 +1,53 @@
+/**
+ * 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 { SUB_KEYS } from "../types.js";
+import { DEFAULT_SOURCE_CLICK_ID } from "./integrationUrls.js";
+const LINK_VALUE_MAX = 255;
+/**
+ * Values are deliberately not percent-encoded so ad-network macro syntax survives.
+ * Reject characters that would instead terminate or split the generated query value.
+ */
+const linkValue = (label) => z
+    .string()
+    .trim()
+    .max(LINK_VALUE_MAX)
+    // eslint-disable-next-line no-control-regex -- matching control chars is the point: reject them.
+    .refine((value) => !/[&#\u0000-\u001f\u007f]/.test(value), {
+    message: `${label} cannot contain &, #, or control characters; percent-encode literal separators.`,
+});
+/** Sub slots are declared one by one so the model can see all five. */
+const subSchema = (key) => linkValue(key)
+    .optional()
+    .describe(`Value or macro for ${key} (analytics only). Defaults to a placeholder named ` +
+    "after the tenant's label for this slot.");
+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.'),
+    cost: linkValue("cost")
+        .optional()
+        .describe("The network's cost macro, e.g. `{cost}`. Adds `&cost=…` so media cost is imported " +
+        "and ROI shows up in get_stats. Omit if the source cannot pass cost."),
+    sub1: subSchema("sub1"),
+    sub2: subSchema("sub2"),
+    sub3: subSchema("sub3"),
+    sub4: subSchema("sub4"),
+    sub5: subSchema("sub5"),
+};
+/** Pull the flat sub1..sub5 args into the record the URL builders take. */
+export function collectSubs(args) {
+    const subs = {};
+    for (const key of SUB_KEYS) {
+        const value = args[key];
+        if (value !== undefined)
+            subs[key] = value;
+    }
+    return subs;
+}
+//# sourceMappingURL=linkArgs.js.map

package/dist/lib/patch.js

@@ -0,0 +1,23 @@
+import { mdCell } from "./format.js";
+/** Render a before → after markdown table. */
+export function renderDiff(changes) {
+    if (changes.length === 0)
+        return "_No field changes._";
+    const lines = [
+        "| Field | From | To |",
+        "|---|---|---|",
+        ...changes.map((c) => `| ${mdCell(c.field)} | ${mdCell(c.from)} | ${mdCell(c.to)} |`),
+    ];
+    return lines.join("\n");
+}
+/** Display helper for nullable / missing values. */
+export function displayValue(value) {
+    if (value === undefined)
+        return "(unset)";
+    if (value === null)
+        return "(null)";
+    if (typeof value === "string" && value.trim() === "")
+        return "(empty)";
+    return String(value);
+}
+//# sourceMappingURL=patch.js.map

package/dist/lib/payoutRules.js

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+export async function fetchPayoutRules(client, campaignId) {
+    const res = await client.get(`/api/campaigns/${encodeURIComponent(campaignId)}/payout_rules`);
+    return res.payout_rules ?? [];
+}
+/** The rule governing one scope: `null` zoneId is the campaign-wide rule. */
+export function findPayoutRule(rules, zoneId) {
+    return rules.find((r) => (zoneId == null ? r.zone_id == null : r.zone_id === zoneId));
+}
+/** Delete the rule governing one scope (`null` zoneId = the campaign-wide rule). */
+export async function deletePayoutScope(client, campaignId, zoneId) {
+    await client.delete(`/api/campaigns/${encodeURIComponent(campaignId)}/payout_rules`, zoneId == null ? undefined : { zone_id: zoneId });
+}
+export async function createPayoutRule(client, campaignId, zoneId, payout) {
+    return client.post(`/api/campaigns/${encodeURIComponent(campaignId)}/payout_rules`, zoneId == null ? { payout } : { payout, zone_id: zoneId });
+}
+/**
+ * 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 async function replacePayout(client, campaignId, zoneId, existing, payout) {
+    await deletePayoutScope(client, campaignId, zoneId);
+    try {
+        return { rule: await createPayoutRule(client, campaignId, zoneId, payout) };
+    }
+    catch (cause) {
+        try {
+            await createPayoutRule(client, campaignId, zoneId, existing.payout);
+            return { rolledBack: existing, cause };
+        }
+        catch (rollbackCause) {
+            return { lost: existing, cause, rollbackCause };
+        }
+    }
+}
+//# sourceMappingURL=payoutRules.js.map

package/dist/lib/targeting.js

@@ -0,0 +1,246 @@
+/**
+ * Targeting helpers shared by the targeting tools.
+ *
+ * The serve path matches `targeting_rules.rule` with an exact, case-sensitive
+ * string compare against what Cloudflare and Bowser produce for the request
+ * (lite-adserver `campaignSelectionService`): `CF-IPCountry` is upper-case
+ * ISO-3166 alpha-2, OS/browser names are Bowser's own spellings, device type is
+ * one of three lower-case words. A rule an operator reads as obviously correct —
+ * `geo: br,mx`, `os: android` — therefore matches nothing, and a whitelist that
+ * matches nothing takes the campaign out of rotation without an error anywhere.
+ * Everything written through these tools is normalised to the serve path's
+ * spelling first, and anything unrecognised comes back as a warning rather than
+ * being silently stored.
+ */
+/**
+ * Seeded types the `/serve` path never evaluates. They accept writes through the
+ * API and then do nothing, so an hours rule reads as a working dayparting setup
+ * while the campaign keeps buying around the clock.
+ */
+export const UNENFORCED_TYPES = {
+    capping: 'not evaluated on /serve — use `unique_users` ("visits/hours") for frequency capping',
+    weekdays: "not evaluated on /serve — no dayparting; pause the campaign instead",
+    hours: "not evaluated on /serve — no dayparting; pause the campaign instead",
+};
+/** Device types `detectDeviceType` can return; anything else never matches. */
+const DEVICE_TYPES = ["desktop", "mobile", "tablet"];
+/**
+ * Bowser OS names worth aliasing, keyed by their lower-case form.
+ *
+ * The `windows_*` and `chrome_os` keys are the ids the dashboard's selectors
+ * wrote into rules before they stored serve-path names; campaigns saved then
+ * still carry them, and the ad server resolves them the same way
+ * (`normalizeOsName` in lite-adserver/src/utils/deviceDetection.ts).
+ */
+const OS_ALIASES = {
+    android: "Android",
+    ios: "iOS",
+    iphone: "iOS",
+    ipad: "iOS",
+    windows: "Windows",
+    windows_7: "Windows",
+    windows_10: "Windows",
+    windows_11: "Windows",
+    "windows 7": "Windows",
+    "windows 10": "Windows",
+    "windows 11": "Windows",
+    "windows phone": "Windows Phone",
+    macos: "macOS",
+    "mac os": "macOS",
+    osx: "macOS",
+    "mac os x": "macOS",
+    linux: "Linux",
+    "chrome os": "Chrome OS",
+    chrome_os: "Chrome OS",
+    chromeos: "Chrome OS",
+};
+/** Bowser browser names worth aliasing, keyed by their lower-case form. */
+const BROWSER_ALIASES = {
+    chrome: "Chrome",
+    chromium: "Chromium",
+    firefox: "Firefox",
+    safari: "Safari",
+    opera: "Opera",
+    edge: "Microsoft Edge",
+    "microsoft edge": "Microsoft Edge",
+    ie: "Internet Explorer",
+    "internet explorer": "Internet Explorer",
+    samsung: "Samsung Internet for Android",
+    samsung_internet: "Samsung Internet for Android",
+    "samsung internet": "Samsung Internet for Android",
+    "samsung internet for android": "Samsung Internet for Android",
+    "android browser": "Android Browser",
+    uc: "UC Browser",
+    "uc browser": "UC Browser",
+    vivaldi: "Vivaldi",
+    yandex: "Yandex Browser",
+    "yandex browser": "Yandex Browser",
+};
+/** Mirrors lite-adserver `isValidZoneId` (UUID v4 or legacy `zone-{id}`). */
+const ZONE_ID_RE = /^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|zone-\d+)$/i;
+/** Mirrors lite-adserver UNIQUE_USERS_MAX_VISITS / _MAX_HOURS. */
+const UNIQUE_USERS_MAX_VISITS = 1000;
+const UNIQUE_USERS_MAX_HOURS = 8760;
+export async function fetchTargetingTypes(client) {
+    const res = await client.get("/api/targeting-rule-types");
+    return res.targeting_rule_types ?? [];
+}
+export async function fetchTargetingRules(client, campaignId) {
+    const res = await client.get(`/api/campaigns/${encodeURIComponent(campaignId)}/targeting_rules`);
+    return res.targeting_rules ?? [];
+}
+/**
+ * Write the campaign's full rule set. The endpoint is a sync, not an append:
+ * every rule the caller wants to keep must be echoed back with its id, or it is
+ * deleted. Callers build `rules` from a fresh read for exactly that reason.
+ */
+export async function syncTargetingRules(client, campaignId, rules) {
+    const res = await client.post(`/api/campaigns/${encodeURIComponent(campaignId)}/targeting_rules`, rules);
+    return res.targeting_rules ?? [];
+}
+/** Strip everything the sync endpoint does not accept back. */
+export function toSyncPayload(rules) {
+    return rules.map((r) => ({
+        ...(r.id !== undefined ? { id: r.id } : {}),
+        targeting_rule_type_id: r.targeting_rule_type_id,
+        targeting_method: r.targeting_method,
+        rule: r.rule,
+    }));
+}
+/** Resolve a caller-supplied type id or name against an already-fetched catalog. */
+export function resolveTargetingType(types, type) {
+    if (types.length === 0) {
+        return { error: "No targeting rule types available in this tenant." };
+    }
+    const raw = String(type).trim();
+    if (typeof type === "number" || /^\d+$/.test(raw)) {
+        const id = typeof type === "number" ? type : parseInt(raw, 10);
+        const match = types.find((t) => t.id === id);
+        if (!match) {
+            const known = types.map((t) => `${t.id}=${t.name}`).join(", ");
+            return { error: `Unknown targeting type id ${id}. Known: ${known}.` };
+        }
+        return { type: match };
+    }
+    const name = raw.toLowerCase();
+    const match = types.find((t) => t.name.toLowerCase() === name);
+    if (!match) {
+        const known = types.map((t) => t.name).join(", ");
+        return { error: `Unknown targeting type "${type}". Known: ${known}.` };
+    }
+    return { type: match };
+}
+/**
+ * Normalise a rule value to the spelling the serve path compares against.
+ * Returns an error for values that provably cannot match, and notes for values
+ * that were rewritten or that could not be checked.
+ */
+export function normalizeRuleValue(typeName, rule) {
+    const raw = rule.trim();
+    if (!raw)
+        return { error: "rule must be a non-empty string." };
+    switch (typeName.toLowerCase()) {
+        case "geo":
+            return normalizeList(raw, "geo", (value) => {
+                if (!/^[A-Za-z]{2}$/.test(value)) {
+                    return {
+                        error: `"${value}" is not an ISO-3166 alpha-2 country code. ` +
+                            "Geo is matched against `CF-IPCountry` (e.g. BR, MX, IN).",
+                    };
+                }
+                return { value: value.toUpperCase() };
+            });
+        case "device_type":
+            return normalizeList(raw, "device_type", (value) => {
+                const lower = value.toLowerCase();
+                if (!DEVICE_TYPES.includes(lower)) {
+                    return {
+                        error: `"${value}" is not a device type. Use ${DEVICE_TYPES.join(", ")}.`,
+                    };
+                }
+                return { value: lower };
+            });
+        case "os":
+            return normalizeList(raw, "os", (value) => aliasOrWarn(value, OS_ALIASES, "OS"));
+        case "browser":
+            return normalizeList(raw, "browser", (value) => aliasOrWarn(value, BROWSER_ALIASES, "browser"));
+        case "zone_id":
+            return normalizeList(raw, "zone_id", (value) => {
+                if (!ZONE_ID_RE.test(value)) {
+                    return {
+                        error: `"${value}" is not a zone id. Zone rules take zone UUIDs ` +
+                            "(see `list_zones`); anything else is dropped by the serve path.",
+                    };
+                }
+                return { value };
+            });
+        case "unique_users":
+            return normalizeUniqueUsers(raw);
+        default:
+            return { value: raw, notes: [] };
+    }
+}
+/** Apply `check` across a comma-separated list, de-duplicating the result. */
+function normalizeList(raw, label, check) {
+    const parts = raw
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+    if (parts.length === 0) {
+        return { error: `${label} rule must list at least one value.` };
+    }
+    const values = [];
+    const notes = [];
+    for (const part of parts) {
+        const checked = check(part);
+        if ("error" in checked)
+            return checked;
+        if (!values.includes(checked.value))
+            values.push(checked.value);
+        if (checked.note)
+            notes.push(checked.note);
+    }
+    const normalized = values.join(",");
+    if (normalized !== raw) {
+        notes.unshift(`Normalised \`${raw}\` → \`${normalized}\` to match the serve path.`);
+    }
+    return { value: normalized, notes };
+}
+/**
+ * OS and browser names come from Bowser and cannot be enumerated safely — an
+ * unknown value may be a real one this list has not seen. Pass it through, but
+ * say so: an unmatched value in a whitelist stops the campaign serving.
+ */
+function aliasOrWarn(value, aliases, label) {
+    const known = aliases[value.toLowerCase()];
+    if (known)
+        return { value: known };
+    return {
+        value,
+        note: `⚠️ \`${value}\` is not a ${label} name this server recognises — it is stored as typed ` +
+            `and matched exactly. Confirm it against a real ${label} value in \`get_stats\` first.`,
+    };
+}
+/** `visits/hours`, matching lite-adserver `parseUniqueUsersRule`. */
+function normalizeUniqueUsers(raw) {
+    const match = /^\s*(\d+)(?:\s*[/,]\s*(\d+))?\s*$/.exec(raw);
+    if (!match) {
+        return {
+            error: `"${raw}" is not a unique_users rule. Use "visits/hours" (e.g. "1/24" for ` +
+                "one impression per user per day). A malformed rule is skipped at serve time, " +
+                "so the cap would silently not apply.",
+        };
+    }
+    const visits = Number(match[1]);
+    const hours = match[2] === undefined ? 24 : Number(match[2]);
+    if (visits < 1 || visits > UNIQUE_USERS_MAX_VISITS) {
+        return { error: `unique_users visits must be 1–${UNIQUE_USERS_MAX_VISITS} (got ${visits}).` };
+    }
+    if (hours < 1 || hours > UNIQUE_USERS_MAX_HOURS) {
+        return { error: `unique_users hours must be 1–${UNIQUE_USERS_MAX_HOURS} (got ${hours}).` };
+    }
+    const value = `${visits}/${hours}`;
+    const notes = value === raw ? [] : [`Normalised \`${raw}\` → \`${value}\` (visits/hours).`];
+    return { value, notes };
+}
+//# sourceMappingURL=targeting.js.map