npm - @affset/mcp - Versions diffs - 0.1.0 → 0.2.0 - Mend

@affset/mcp 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (66) hide show

package/.env.example +5 -0
package/README.md +158 -37
package/dist/client.d.ts +43 -0
package/dist/client.js +15 -2
package/dist/config.d.ts +7 -0
package/dist/config.js +15 -54
package/dist/core.d.ts +18 -0
package/dist/core.js +18 -0
package/dist/docs.d.ts +39 -0
package/dist/docs.js +105 -0
package/dist/index.d.ts +2 -0
package/dist/index.js +0 -0
package/dist/lib/format.d.ts +46 -0
package/dist/lib/format.js +3 -0
package/dist/lib/integrationUrls.d.ts +57 -0
package/dist/lib/linkArgs.d.ts +27 -0
package/dist/lib/patch.d.ts +10 -0
package/dist/lib/payoutRules.d.ts +38 -0
package/dist/lib/readBody.d.ts +17 -0
package/dist/lib/readBody.js +69 -0
package/dist/lib/targeting.d.ts +51 -0
package/dist/lib/time.d.ts +38 -0
package/dist/lib/toolResult.d.ts +7 -0
package/dist/lib/urls.d.ts +2 -0
package/dist/lib/zones.d.ts +24 -0
package/dist/registerTools.d.ts +40 -0
package/dist/registerTools.js +401 -0
package/dist/runtimeConfig.d.ts +37 -0
package/dist/runtimeConfig.js +93 -0
package/dist/server.d.ts +4 -0
package/dist/server.js +3 -306
package/dist/tools/createCampaign.d.ts +25 -0
package/dist/tools/createCampaign.js +3 -2
package/dist/tools/createTeamMember.d.ts +26 -0
package/dist/tools/createTeamMember.js +204 -0
package/dist/tools/createZone.d.ts +22 -0
package/dist/tools/cutZones.d.ts +29 -0
package/dist/tools/deletePayoutRule.d.ts +16 -0
package/dist/tools/getCampaign.d.ts +12 -0
package/dist/tools/getCampaign.js +150 -0
package/dist/tools/getStats.d.ts +40 -0
package/dist/tools/getStats.js +37 -2
package/dist/tools/getTrackingLink.d.ts +23 -0
package/dist/tools/getZoneUrl.d.ts +21 -0
package/dist/tools/listCampaigns.d.ts +23 -0
package/dist/tools/listConversions.d.ts +29 -0
package/dist/tools/listPayoutRules.d.ts +12 -0
package/dist/tools/listSubLabels.d.ts +5 -0
package/dist/tools/listTargetingRules.d.ts +12 -0
package/dist/tools/listTargetingTypes.d.ts +5 -0
package/dist/tools/listTeam.d.ts +14 -0
package/dist/tools/listZones.d.ts +23 -0
package/dist/tools/removeTargetingRule.d.ts +21 -0
package/dist/tools/setCampaignStatus.d.ts +18 -0
package/dist/tools/setPayoutGoal.d.ts +16 -0
package/dist/tools/setPayoutRule.d.ts +18 -0
package/dist/tools/setSubLabels.d.ts +22 -0
package/dist/tools/setTargetingRule.d.ts +21 -0
package/dist/tools/updateCampaign.d.ts +35 -0
package/dist/tools/updateZone.d.ts +25 -0
package/dist/tools/whoami.d.ts +6 -0
package/dist/types.d.ts +210 -0
package/dist/types.js +1 -0
package/dist/version.d.ts +7 -0
package/dist/version.js +8 -0
package/package.json +16 -2

package/dist/docs.js ADDED Viewed

@@ -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 ADDED Viewed

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

package/dist/index.js CHANGED Viewed

File without changes

package/dist/lib/format.d.ts ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -0,0 +1,57 @@
+/**
+ * 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 } from "../types.js";
+/** Query parameter carrying the traffic source's click token. */
+export declare 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 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 RichAds 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;
+}
+/** `/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;
+/** "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;

package/dist/lib/linkArgs.d.ts ADDED Viewed

@@ -0,0 +1,27 @@
+/**
+ * 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;

package/dist/lib/patch.d.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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

package/dist/lib/targeting.d.ts ADDED Viewed

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+import type { AffsetClient } from "../client.js";
+import type { TargetingRule, TargetingRuleType } from "../types.js";
+export type TargetingMethod = "whitelist" | "blacklist";
+/**
+ * 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 declare const UNENFORCED_TYPES: Record<string, string>;
+export declare function fetchTargetingTypes(client: AffsetClient): Promise<TargetingRuleType[]>;
+export declare function fetchTargetingRules(client: AffsetClient, campaignId: string): Promise<TargetingRule[]>;
+/**
+ * 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 declare function syncTargetingRules(client: AffsetClient, campaignId: string, rules: TargetingRule[]): Promise<TargetingRule[]>;
+/** Strip everything the sync endpoint does not accept back. */
+export declare function toSyncPayload(rules: TargetingRule[]): TargetingRule[];
+/** Resolve a caller-supplied type id or name against an already-fetched catalog. */
+export declare function resolveTargetingType(types: TargetingRuleType[], type: string | number): {
+    type: TargetingRuleType;
+} | {
+    error: string;
+};
+export type NormalizedRule = {
+    value: string;
+    notes: string[];
+};
+/**
+ * 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 declare function normalizeRuleValue(typeName: string, rule: string): NormalizedRule | {
+    error: string;
+};

package/dist/lib/time.d.ts ADDED Viewed

@@ -0,0 +1,38 @@
+/**
+ * Date-range resolution for stats queries.
+ *
+ * Every boundary here is computed in the TENANT's timezone, not the timezone of
+ * the machine running this server. The API buckets `group_by=date` by the tenant
+ * timezone, so resolving "today" against the operator's laptop clock would ask
+ * for a window that straddles two of the buckets it gets back — a single "today"
+ * arriving as two partial rows. Callers fetch the tenant timezone (see
+ * AffsetClient#getTenantTimezone) and pass it in.
+ */
+export declare const RANGE_PRESETS: readonly ["today", "yesterday", "last_7_days", "last_30_days", "this_month"];
+export type RangePreset = (typeof RANGE_PRESETS)[number];
+export interface ResolvedRange {
+    /** Inclusive lower bound, epoch ms. */
+    from: number;
+    /** Inclusive upper bound, epoch ms. */
+    to: number;
+    /** Human label for display. */
+    label: string;
+}
+/**
+ * Parse one campaign schedule boundary. Date-only values use the tenant's
+ * timezone; explicit ISO timestamps and epoch milliseconds remain exact.
+ */
+export declare function parseCampaignDateBound(value: string | number | null, role: "start" | "end", timeZone: string): number | null;
+/**
+ * Resolve a range from an optional preset and/or explicit from/to bounds.
+ * Explicit bounds win over the preset. All day boundaries are in `timeZone`
+ * (the tenant's), so the window lines up with the API's date buckets.
+ */
+export declare function resolveRange(preset: RangePreset | undefined, from: string | undefined, to: string | undefined, timeZone: string): ResolvedRange;
+/**
+ * Format an instant as `YYYY-MM-DD HH:mm` in the tenant timezone. Row timestamps
+ * have to agree with the date buckets stats are read in: a conversion at 23:30
+ * tenant-local rendered in UTC lands on the next day's row and reads as a
+ * missing conversion.
+ */
+export declare function formatInstant(ms: number, timeZone: string): string;

package/dist/lib/toolResult.d.ts ADDED Viewed

@@ -0,0 +1,7 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/** Build a successful text tool result. */
+export declare function textResult(body: string): CallToolResult;
+/** Build an error tool result (isError: true). */
+export declare function errorResult(err: unknown): CallToolResult;
+/** Build an error tool result from a plain string. */
+export declare function textError(body: string): CallToolResult;

package/dist/lib/urls.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ /** Validate http(s) URL; returns an error message or undefined when ok. */
2	+ export declare function httpUrlError(value: string, label: string): string \| undefined;

package/dist/lib/zones.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+/**
+ * Zone lookup shared by every tool that needs a traffic source: campaign creation
+ * and both integration-URL tools all take an optional `zone_id` and auto-pick when
+ * the namespace has exactly one active zone.
+ */
+import { type AffsetClient } from "../client.js";
+import type { Zone } from "../types.js";
+export type ResolvedZone = {
+    zone: Zone;
+    inactiveWarning?: string;
+};
+export type ZoneResolution = ResolvedZone | {
+    error: string;
+};
+/**
+ * Resolve the zone to build URLs against. An explicit id is fetched directly — the
+ * paginated list must not be the arbiter of whether a zone exists.
+ */
+export declare function resolveZone(client: AffsetClient, zoneId: string | undefined): Promise<ZoneResolution>;
+/**
+ * The line every integration URL needs under it: without a postback URL on the zone,
+ * conversions never make it back to the traffic source and its optimizer stays blind.
+ */
+export declare function zonePostbackNote(zone: Zone): string;

package/dist/registerTools.d.ts ADDED Viewed

@@ -0,0 +1,40 @@
+import { type Config } from "./runtimeConfig.js";
+/**
+ * Structural stand-in for the SDK's `McpServer`, so a consumer's own SDK
+ * install is accepted. `McpServer` carries private fields, which makes two
+ * copies of the class (this package's and a consumer's — e.g. the Workers
+ * gateway bundling its own `@modelcontextprotocol/sdk`) nominally
+ * incompatible even at identical versions. Method-parameter bivariance makes
+ * any real `McpServer` assignable to this shape; nothing else plausibly is.
+ *
+ * The zod schemas behind `inputSchema` stay internal to this package, so
+ * consumers never mix zod instances at the type level (they may bundle zod
+ * v4 while this package uses v3 — the MCP SDK detects the flavor per call).
+ */
+export interface AffsetToolServer {
+    registerTool(name: string, config: object, callback: (...args: never[]) => unknown): unknown;
+    registerResource(name: string, uri: string, metadata: object, callback: never): unknown;
+}
+export interface ToolCallEvent {
+    toolName: string;
+    durationMs: number;
+    status: "ok" | "error";
+}
+export interface RegisterAffsetToolsOptions {
+    /**
+     * Optional transport-owned audit hook. It receives metadata only, never tool
+     * arguments or output. Hook failures are isolated from the tool result.
+     */
+    onToolCall?: (event: ToolCallEvent) => void | Promise<void>;
+}
+/**
+ * Register the full affset tool roster and docs resources against `config`.
+ * The single source of truth for the roster: the stdio entrypoint
+ * (`createServer`) and the remote gateway's `McpAgent` both call exactly this,
+ * so the two transports cannot drift (REMOTE-MCP-PRD.md §5.6).
+ *
+ * When `config.readOnly` is set, every tool that is not `readOnlyHint: true`
+ * is skipped — identical semantics to AFFSET_READ_ONLY on stdio and to a
+ * `read`-scoped OAuth grant on the gateway.
+ */
+export declare function registerAffsetTools(toolServer: AffsetToolServer, config: Config, options?: RegisterAffsetToolsOptions): void;