@adport/core 0.1.0

package/dist/index.js

@@ -0,0 +1,1151 @@
+// src/errors.ts
+var AdportError = class extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "AdportError";
+  }
+  code;
+  details;
+  toJSON() {
+    return { error: this.code, message: this.message, details: this.details };
+  }
+};
+
+// src/paths.ts
+import os from "os";
+import path from "path";
+function adportHome() {
+  return process.env.ADPORT_HOME ?? path.join(os.homedir(), ".config", "adport");
+}
+
+// src/model.ts
+var METRICS = [
+  "spend",
+  "impressions",
+  "clicks",
+  "conversions",
+  "conversion_value",
+  "ctr",
+  "cpc",
+  "cpm",
+  "cpa",
+  "roas"
+];
+var ENTITY_LEVELS = ["account", "campaign", "ad_group", "ad"];
+var DATE_PRESETS = ["today", "yesterday", "last_7_days", "last_30_days", "this_month"];
+function iso(d) {
+  return d.toISOString().slice(0, 10);
+}
+function resolveDateRange(range, now = /* @__PURE__ */ new Date()) {
+  if (typeof range !== "string") return range;
+  const today = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+  const daysAgo = (n) => new Date(today.getTime() - n * 864e5);
+  switch (range) {
+    case "today":
+      return { start: iso(today), end: iso(today) };
+    case "yesterday":
+      return { start: iso(daysAgo(1)), end: iso(daysAgo(1)) };
+    case "last_7_days":
+      return { start: iso(daysAgo(7)), end: iso(daysAgo(1)) };
+    case "last_30_days":
+      return { start: iso(daysAgo(30)), end: iso(daysAgo(1)) };
+    case "this_month":
+      return { start: iso(new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1))), end: iso(today) };
+  }
+}
+function rangeDayCount(range) {
+  const start = Date.parse(`${range.start}T00:00:00Z`);
+  const end = Date.parse(`${range.end}T00:00:00Z`);
+  return Math.max(1, Math.round((end - start) / 864e5) + 1);
+}
+
+// src/provider.ts
+var ProviderRegistry = class {
+  providers = /* @__PURE__ */ new Map();
+  register(provider) {
+    this.providers.set(provider.id, provider);
+  }
+  get(id) {
+    const provider = this.providers.get(id);
+    if (!provider) {
+      throw new AdportError(
+        "NOT_CONNECTED",
+        `Provider "${id}" is not connected. Run \`adport connect ${id}\` first.`
+      );
+    }
+    return provider;
+  }
+  list() {
+    return [...this.providers.values()];
+  }
+};
+
+// src/audit/packs/core-performance.ts
+function isActive(status) {
+  return !/(PAUS|DISABLE|REMOV|DELET|CLOS|ARCHIV)/i.test(status ?? "ENABLED");
+}
+var zeroConversionSpend = {
+  id: "zero-conversion-spend",
+  title: "Active campaign spending with zero conversions",
+  description: "Flags campaigns that spent above the threshold over the range without a single tracked conversion.",
+  evaluate(ctx) {
+    const minSpend = ctx.config.zero_conversion_min_spend;
+    return ctx.rows.filter((row) => isActive(row.entity.status)).filter((row) => (row.metrics.spend ?? 0) >= minSpend && (row.metrics.conversions ?? 0) === 0).map((row) => ({
+      entity: row.entity,
+      severity: (row.metrics.spend ?? 0) >= minSpend * 3 ? "critical" : "warn",
+      title: `"${row.entity.name}" spent ${row.metrics.spend} with 0 conversions`,
+      detail: `Campaign ${row.entity.id} spent ${row.metrics.spend} between ${ctx.range.start} and ${ctx.range.end} without any tracked conversion. Either conversion tracking is broken or the spend is wasted.`,
+      recommendation: "Verify conversion tracking first; if tracking is correct, pause the campaign and rework targeting/creative.",
+      proposedAction: ctx.actions.pauseCampaign?.(ctx.accountId, row.entity.id),
+      metrics: row.metrics
+    }));
+  }
+};
+var lowCtr = {
+  id: "low-ctr",
+  title: "High impressions with very low CTR",
+  description: "Flags campaigns whose creative/targeting is not resonating (lots of impressions, few clicks).",
+  evaluate(ctx) {
+    const minImpressions = ctx.config.low_ctr_min_impressions;
+    const threshold = ctx.config.low_ctr_threshold_pct;
+    return ctx.rows.filter((row) => isActive(row.entity.status)).filter((row) => (row.metrics.impressions ?? 0) >= minImpressions && (row.metrics.ctr ?? 100) < threshold).map((row) => ({
+      entity: row.entity,
+      severity: "warn",
+      title: `"${row.entity.name}" CTR ${row.metrics.ctr}% over ${row.metrics.impressions} impressions`,
+      detail: `CTR is below ${threshold}% despite meaningful reach \u2014 the ad or audience likely needs work.`,
+      recommendation: "Review creative and audience targeting; test new headlines/assets before touching budgets.",
+      metrics: row.metrics
+    }));
+  }
+};
+var cpaOutlier = {
+  id: "cpa-outlier",
+  title: "Campaign CPA far above account median",
+  description: "Flags converting campaigns whose cost per conversion is a large multiple of the account median.",
+  evaluate(ctx) {
+    const multiplier = ctx.config.cpa_outlier_multiplier;
+    const converting = ctx.rows.filter((row) => (row.metrics.conversions ?? 0) > 0 && (row.metrics.cpa ?? 0) > 0);
+    if (converting.length < 3) return [];
+    const cpas = converting.map((row) => row.metrics.cpa).sort((a, b) => a - b);
+    const median = cpas[Math.floor(cpas.length / 2)];
+    return converting.filter((row) => row.metrics.cpa > median * multiplier).map((row) => ({
+      entity: row.entity,
+      severity: "warn",
+      title: `"${row.entity.name}" CPA ${row.metrics.cpa} vs account median ${median}`,
+      detail: `Cost per conversion is more than ${multiplier}\xD7 the account median over the range.`,
+      recommendation: "Shift budget toward lower-CPA campaigns, or tighten targeting/bids here.",
+      metrics: row.metrics
+    }));
+  }
+};
+var negativeRoas = {
+  id: "negative-roas",
+  title: "Campaign returning less than it spends",
+  description: "Flags campaigns with tracked revenue whose ROAS is below break-even.",
+  evaluate(ctx) {
+    const minSpend = ctx.config.roas_min_spend;
+    return ctx.rows.filter((row) => isActive(row.entity.status)).filter(
+      (row) => (row.metrics.spend ?? 0) >= minSpend && (row.metrics.conversion_value ?? 0) > 0 && (row.metrics.roas ?? 0) < 1
+    ).map((row) => ({
+      entity: row.entity,
+      severity: "warn",
+      title: `"${row.entity.name}" ROAS ${row.metrics.roas} (below break-even)`,
+      detail: `Spent ${row.metrics.spend} for ${row.metrics.conversion_value} in tracked revenue over the range.`,
+      recommendation: "Check margins and attribution windows; consider bid/budget reduction or audience changes.",
+      metrics: row.metrics
+    }));
+  }
+};
+var corePerformancePack = {
+  name: "core-performance",
+  version: "0.1.0",
+  rules: [zeroConversionSpend, lowCtr, cpaOutlier, negativeRoas],
+  defaults: {
+    zero_conversion_min_spend: 50,
+    low_ctr_min_impressions: 5e3,
+    low_ctr_threshold_pct: 0.5,
+    cpa_outlier_multiplier: 2.5,
+    roas_min_spend: 50
+  }
+};
+
+// src/audit/store.ts
+import { promises as fs } from "fs";
+import path2 from "path";
+var FindingsStore = class {
+  constructor(dir = path2.join(adportHome(), "findings")) {
+    this.dir = dir;
+  }
+  dir;
+  file(id) {
+    return path2.join(this.dir, `${id.replace(/[^a-zA-Z0-9_.:-]/g, "_")}.json`);
+  }
+  async list(filter = {}) {
+    let names;
+    try {
+      names = await fs.readdir(this.dir);
+    } catch {
+      return [];
+    }
+    const findings = [];
+    for (const name of names) {
+      if (!name.endsWith(".json")) continue;
+      const finding = JSON.parse(await fs.readFile(path2.join(this.dir, name), "utf8"));
+      if (filter.status && finding.status !== filter.status) continue;
+      if (filter.provider && finding.provider !== filter.provider) continue;
+      findings.push(finding);
+    }
+    const order = { critical: 0, warn: 1, info: 2 };
+    return findings.sort((a, b) => (order[a.severity] ?? 3) - (order[b.severity] ?? 3));
+  }
+  async get(id) {
+    try {
+      return JSON.parse(await fs.readFile(this.file(id), "utf8"));
+    } catch (err) {
+      if (err.code === "ENOENT") return void 0;
+      throw err;
+    }
+  }
+  async save(finding) {
+    await fs.mkdir(this.dir, { recursive: true, mode: 448 });
+    await fs.writeFile(this.file(finding.id), JSON.stringify(finding, null, 2), { mode: 384 });
+  }
+  async setStatus(id, status) {
+    const finding = await this.get(id);
+    if (!finding) throw new Error(`Finding not found: ${id}`);
+    const updated = { ...finding, status, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    await this.save(updated);
+    return updated;
+  }
+};
+
+// src/audit/runner.ts
+var AuditRunner = class {
+  constructor(providers, store = new FindingsStore()) {
+    this.providers = providers;
+    this.store = store;
+  }
+  providers;
+  store;
+  async run(options = {}) {
+    const range = resolveDateRange(options.dateRange ?? "last_30_days");
+    const packs = options.packs ?? [corePerformancePack];
+    const providers = options.provider ? [this.providers.get(options.provider)] : this.providers.list();
+    const findings = [];
+    let evaluatedAccounts = 0;
+    for (const provider of providers) {
+      const report = await provider.report({
+        accountIds: options.accountIds,
+        level: "campaign",
+        metrics: ["spend", "impressions", "clicks", "conversions", "conversion_value", "ctr", "cpc", "cpa", "roas"],
+        dateRange: range,
+        limit: 1e3
+      });
+      const byAccount = /* @__PURE__ */ new Map();
+      for (const row of report.rows) {
+        const rows = byAccount.get(row.accountId) ?? [];
+        rows.push(row);
+        byAccount.set(row.accountId, rows);
+      }
+      const actions = provider.standardActions?.() ?? {};
+      for (const [accountId, rows] of byAccount) {
+        evaluatedAccounts += 1;
+        for (const pack of packs) {
+          const config = { ...pack.defaults, ...options.configOverrides };
+          for (const rule of pack.rules) {
+            for (const ruleFinding of rule.evaluate({ provider: provider.id, accountId, rows, range, actions, config })) {
+              const id = `${rule.id}:${provider.id}:${accountId}:${ruleFinding.entity.id}`;
+              const existing = await this.store.get(id);
+              if (existing && existing.status !== "open") continue;
+              const now = (/* @__PURE__ */ new Date()).toISOString();
+              const finding = {
+                id,
+                ruleId: rule.id,
+                severity: ruleFinding.severity,
+                provider: provider.id,
+                accountId,
+                entity: ruleFinding.entity,
+                title: ruleFinding.title,
+                detail: ruleFinding.detail,
+                recommendation: ruleFinding.recommendation,
+                proposedAction: ruleFinding.proposedAction,
+                metrics: ruleFinding.metrics,
+                dateRange: range,
+                status: "open",
+                createdAt: existing?.createdAt ?? now,
+                updatedAt: now
+              };
+              await this.store.save(finding);
+              findings.push(finding);
+            }
+          }
+        }
+      }
+    }
+    return {
+      findings,
+      counts: {
+        critical: findings.filter((f) => f.severity === "critical").length,
+        warn: findings.filter((f) => f.severity === "warn").length,
+        info: findings.filter((f) => f.severity === "info").length
+      },
+      evaluatedAccounts,
+      range
+    };
+  }
+};
+
+// src/audit/tools.ts
+import { z } from "zod";
+
+// src/tools/registry.ts
+function defineTool(def) {
+  return {
+    ...def,
+    annotations: def.annotations ?? { readOnly: false }
+  };
+}
+var ToolRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  register(tools) {
+    for (const tool of Array.isArray(tools) ? tools : [tools]) {
+      if (this.tools.has(tool.name)) {
+        throw new Error(`Tool "${tool.name}" is already registered`);
+      }
+      this.tools.set(tool.name, tool);
+    }
+  }
+  list() {
+    return [...this.tools.values()];
+  }
+  get(name) {
+    const tool = this.tools.get(name);
+    if (!tool) throw new AdportError("UNKNOWN_TOOL", `Unknown tool: ${name}`);
+    return tool;
+  }
+  async call(name, rawInput, ctx) {
+    const tool = this.get(name);
+    const parsed = tool.input.safeParse(rawInput ?? {});
+    if (!parsed.success) {
+      throw new AdportError("INVALID_INPUT", `Invalid input for ${name}`, parsed.error.issues);
+    }
+    return tool.handler(parsed.data, ctx);
+  }
+};
+
+// src/audit/tools.ts
+var dateRangeSchema = z.union([
+  z.enum(DATE_PRESETS),
+  z.object({
+    start: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+    end: z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
+  })
+]);
+function auditTools() {
+  return [
+    defineTool({
+      name: "audit_run",
+      namespace: "audit",
+      description: "Run the cross-platform audit rule packs over connected accounts (campaign level). Returns structured findings with recommendations; some carry a ready-to-apply proposed action. Reads ad data only \u2014 never mutates anything.",
+      input: z.object({
+        provider: z.string().optional(),
+        account_ids: z.array(z.string()).optional(),
+        date_range: dateRangeSchema.default("last_30_days")
+      }),
+      annotations: { readOnly: true },
+      async handler(input, ctx) {
+        const runner = new AuditRunner(ctx.providers);
+        const result = await runner.run({
+          provider: input.provider,
+          accountIds: input.account_ids,
+          dateRange: input.date_range
+        });
+        return result;
+      }
+    }),
+    defineTool({
+      name: "recommendations_list",
+      namespace: "audit",
+      description: "List persisted audit findings/recommendations (default: open ones), most severe first.",
+      input: z.object({
+        status: z.enum(["open", "dismissed", "applied"]).default("open"),
+        provider: z.string().optional()
+      }),
+      annotations: { readOnly: true },
+      async handler(input) {
+        const findings = await new FindingsStore().list(input);
+        return { findings, count: findings.length };
+      }
+    }),
+    defineTool({
+      name: "recommendation_dismiss",
+      namespace: "audit",
+      description: "Dismiss a finding (it will not be re-opened by future audit runs).",
+      input: z.object({ finding_id: z.string() }),
+      annotations: { readOnly: false },
+      async handler(input) {
+        const finding = await new FindingsStore().setStatus(input.finding_id, "dismissed");
+        return { finding };
+      }
+    }),
+    defineTool({
+      name: "recommendation_apply",
+      namespace: "audit",
+      description: "Execute a finding's proposed action through the normal two-step write flow: first call returns the dry-run preview and pending_operation_id; second call (with the id) applies and marks the finding applied.",
+      input: z.object({
+        finding_id: z.string(),
+        pending_operation_id: z.string().optional()
+      }),
+      annotations: { readOnly: false },
+      async handler(input, ctx) {
+        if (!ctx.registry) {
+          throw new AdportError("PROVIDER_ERROR", "recommendation_apply requires a tool registry in context");
+        }
+        const store = new FindingsStore();
+        const finding = await store.get(input.finding_id);
+        if (!finding) throw new AdportError("INVALID_INPUT", `Finding not found: ${input.finding_id}`);
+        if (finding.status !== "open") {
+          throw new AdportError("INVALID_INPUT", `Finding ${input.finding_id} is ${finding.status}, not open`);
+        }
+        if (!finding.proposedAction) {
+          throw new AdportError(
+            "INVALID_INPUT",
+            `Finding ${input.finding_id} has no proposed action \u2014 it needs human judgment (${finding.recommendation})`
+          );
+        }
+        const result = await ctx.registry.call(
+          finding.proposedAction.tool,
+          {
+            ...finding.proposedAction.input,
+            ...input.pending_operation_id ? { pending_operation_id: input.pending_operation_id } : {}
+          },
+          ctx
+        );
+        if (result.status === "applied") {
+          await store.setStatus(finding.id, "applied");
+        }
+        return { finding_id: finding.id, action: finding.proposedAction, result };
+      }
+    })
+  ];
+}
+
+// src/credentials/store.ts
+import { promises as fs2 } from "fs";
+import path3 from "path";
+var EMPTY = { version: 1, credentials: {} };
+var CredentialStore = class {
+  constructor(dir = adportHome()) {
+    this.dir = dir;
+  }
+  dir;
+  file() {
+    return path3.join(this.dir, "credentials.json");
+  }
+  async read() {
+    try {
+      const raw = await fs2.readFile(this.file(), "utf8");
+      return JSON.parse(raw);
+    } catch (err) {
+      if (err.code === "ENOENT") return structuredClone(EMPTY);
+      throw err;
+    }
+  }
+  async write(data) {
+    await fs2.mkdir(this.dir, { recursive: true, mode: 448 });
+    await fs2.writeFile(this.file(), `${JSON.stringify(data, null, 2)}
+`, { mode: 384 });
+    await fs2.chmod(this.file(), 384);
+  }
+  async get(provider) {
+    const file = await this.read();
+    return file.credentials[provider];
+  }
+  async list() {
+    const file = await this.read();
+    return Object.values(file.credentials);
+  }
+  async set(record) {
+    const file = await this.read();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const existing = file.credentials[record.provider];
+    const full = { ...record, createdAt: existing?.createdAt ?? now, updatedAt: now };
+    file.credentials[record.provider] = full;
+    await this.write(file);
+    return full;
+  }
+  async delete(provider) {
+    const file = await this.read();
+    if (!(provider in file.credentials)) return false;
+    delete file.credentials[provider];
+    await this.write(file);
+    return true;
+  }
+};
+
+// src/policy/policy.ts
+import { promises as fs3 } from "fs";
+import path4 from "path";
+import YAML from "yaml";
+import { z as z2 } from "zod";
+var policySchema = z2.object({
+  /** Writes must be validated (dry-run) before they can be applied. */
+  require_validation: z2.boolean().default(true),
+  /** Created campaigns/ad groups/ads are coerced to PAUSED. */
+  paused_creation: z2.boolean().default(true),
+  /** Reject budget changes exceeding this percentage of the current value. null = no cap. */
+  max_budget_delta_pct: z2.number().positive().nullable().default(25),
+  /** Reject any budget set above this absolute value (micros). null = no cap. */
+  max_daily_budget_micros: z2.number().positive().nullable().default(null),
+  /** Account ids that no write may touch. */
+  protected_accounts: z2.array(z2.string()).default([]),
+  /** How long a validated pending operation stays applicable. */
+  pending_ttl_minutes: z2.number().positive().default(15)
+});
+var DEFAULT_POLICY = policySchema.parse({});
+async function loadPolicy(explicitPath) {
+  const candidates = [
+    explicitPath,
+    process.env.ADPORT_POLICY,
+    path4.join(process.cwd(), "adport.policy.yaml"),
+    path4.join(adportHome(), "policy.yaml")
+  ].filter((p) => Boolean(p));
+  for (const candidate of candidates) {
+    let raw;
+    try {
+      raw = await fs3.readFile(candidate, "utf8");
+    } catch {
+      if (candidate === explicitPath || candidate === process.env.ADPORT_POLICY) {
+        throw new Error(`Policy file not found: ${candidate}`);
+      }
+      continue;
+    }
+    const parsed = policySchema.safeParse(YAML.parse(raw) ?? {});
+    if (!parsed.success) {
+      throw new Error(`Invalid policy file ${candidate}: ${parsed.error.message}`);
+    }
+    return { policy: parsed.data, source: candidate };
+  }
+  return { policy: DEFAULT_POLICY, source: "defaults" };
+}
+
+// src/policy/pending.ts
+import { promises as fs4 } from "fs";
+import path5 from "path";
+var PendingStore = class {
+  constructor(dir = path5.join(adportHome(), "pending")) {
+    this.dir = dir;
+  }
+  dir;
+  file(id) {
+    if (!/^[a-zA-Z0-9-]+$/.test(id)) throw new Error(`Invalid pending operation id: ${id}`);
+    return path5.join(this.dir, `${id}.json`);
+  }
+  async put(op) {
+    await fs4.mkdir(this.dir, { recursive: true, mode: 448 });
+    await fs4.writeFile(this.file(op.id), JSON.stringify(op, null, 2), { mode: 384 });
+  }
+  async get(id) {
+    try {
+      return JSON.parse(await fs4.readFile(this.file(id), "utf8"));
+    } catch (err) {
+      if (err.code === "ENOENT") return void 0;
+      throw err;
+    }
+  }
+  async delete(id) {
+    await fs4.rm(this.file(id), { force: true });
+  }
+  /** Remove expired entries. Called opportunistically; never throws on races. */
+  async sweep(now = /* @__PURE__ */ new Date()) {
+    let names;
+    try {
+      names = await fs4.readdir(this.dir);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      if (!name.endsWith(".json")) continue;
+      try {
+        const op = JSON.parse(await fs4.readFile(path5.join(this.dir, name), "utf8"));
+        if (Date.parse(op.expiresAt) < now.getTime()) {
+          await fs4.rm(path5.join(this.dir, name), { force: true });
+        }
+      } catch {
+      }
+    }
+  }
+};
+
+// src/policy/audit.ts
+import { promises as fs5 } from "fs";
+import path6 from "path";
+var AuditLog = class {
+  constructor(dir = path6.join(adportHome(), "audit")) {
+    this.dir = dir;
+  }
+  dir;
+  file(now = /* @__PURE__ */ new Date()) {
+    const month = now.toISOString().slice(0, 7);
+    return path6.join(this.dir, `audit-${month}.jsonl`);
+  }
+  async append(entry) {
+    await fs5.mkdir(this.dir, { recursive: true, mode: 448 });
+    const full = { ts: (/* @__PURE__ */ new Date()).toISOString(), ...entry };
+    await fs5.appendFile(this.file(), `${JSON.stringify(full)}
+`, { mode: 384 });
+  }
+  /** Most recent entries, newest last. Reads across all monthly files. */
+  async read(limit = 50) {
+    let names;
+    try {
+      names = (await fs5.readdir(this.dir)).filter((n) => n.endsWith(".jsonl")).sort();
+    } catch {
+      return [];
+    }
+    const entries = [];
+    for (const name of names) {
+      const raw = await fs5.readFile(path6.join(this.dir, name), "utf8");
+      for (const line of raw.split("\n")) {
+        if (line.trim()) entries.push(JSON.parse(line));
+      }
+    }
+    return entries.slice(-limit);
+  }
+};
+
+// src/policy/engine.ts
+import { createHash, randomUUID } from "crypto";
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, canonicalize(v)])
+    );
+  }
+  return value;
+}
+function hashOperation(op) {
+  const canonical = canonicalize({
+    tool: op.tool,
+    provider: op.provider,
+    accountId: op.accountId,
+    kind: op.kind,
+    payload: op.payload
+  });
+  return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+var PolicyEngine = class {
+  constructor(policy, pending = new PendingStore(), audit = new AuditLog()) {
+    this.policy = policy;
+    this.pending = pending;
+    this.audit = audit;
+  }
+  policy;
+  pending;
+  audit;
+  guard() {
+    return { forcePausedCreation: this.policy.paused_creation };
+  }
+  async validate(provider, op) {
+    await this.pending.sweep();
+    await this.checkStaticPolicy(op);
+    const preview = await provider.previewWrite(op, this.guard());
+    await this.checkBudgetPolicy(op, preview);
+    const id = randomUUID();
+    const now = Date.now();
+    const expiresAt = new Date(now + this.policy.pending_ttl_minutes * 6e4).toISOString();
+    await this.pending.put({
+      id,
+      provider: provider.id,
+      opHash: hashOperation(op),
+      op,
+      preview,
+      createdAt: new Date(now).toISOString(),
+      expiresAt
+    });
+    await this.audit.append({
+      event: "validated",
+      provider: provider.id,
+      tool: op.tool,
+      accountId: op.accountId,
+      pendingId: id,
+      summary: preview.summary
+    });
+    return { pendingOperationId: id, preview, expiresAt };
+  }
+  async apply(provider, op, pendingId) {
+    const pending = await this.pending.get(pendingId);
+    if (!pending) {
+      throw new AdportError(
+        "PENDING_NOT_FOUND",
+        `No pending operation "${pendingId}". Validate first: call the tool without pending_operation_id.`
+      );
+    }
+    if (Date.parse(pending.expiresAt) < Date.now()) {
+      await this.pending.delete(pendingId);
+      throw new AdportError(
+        "PENDING_EXPIRED",
+        `Pending operation ${pendingId} expired at ${pending.expiresAt}. Validate again.`
+      );
+    }
+    if (pending.provider !== provider.id || pending.opHash !== hashOperation(op)) {
+      throw new AdportError(
+        "PENDING_MISMATCH",
+        "The operation differs from what was validated. Re-validate with the exact arguments you intend to apply."
+      );
+    }
+    await this.checkStaticPolicy(op);
+    const result = await provider.applyWrite(op, this.guard());
+    await this.audit.append({
+      event: "applied",
+      provider: provider.id,
+      tool: op.tool,
+      accountId: op.accountId,
+      pendingId,
+      summary: pending.preview.summary,
+      details: { resourceIds: result.resourceIds }
+    });
+    await this.pending.delete(pendingId);
+    return { result, preview: pending.preview };
+  }
+  async checkStaticPolicy(op) {
+    if (this.policy.protected_accounts.includes(op.accountId)) {
+      await this.reject(op, `Account ${op.accountId} is protected by policy`);
+    }
+  }
+  async checkBudgetPolicy(op, preview) {
+    const pctCap = this.policy.max_budget_delta_pct;
+    const absCap = this.policy.max_daily_budget_micros;
+    for (const delta of preview.budgetDeltas) {
+      if (absCap !== null && delta.toMicros > absCap) {
+        await this.reject(
+          op,
+          `${delta.target}: ${delta.toMicros} micros exceeds the absolute budget cap (${absCap})`
+        );
+      }
+      if (pctCap !== null && delta.fromMicros !== void 0 && delta.fromMicros > 0) {
+        const pct = Math.abs(delta.toMicros - delta.fromMicros) / delta.fromMicros * 100;
+        if (pct > pctCap) {
+          await this.reject(
+            op,
+            `${delta.target}: ${pct.toFixed(1)}% change exceeds the ${pctCap}% budget-delta cap`
+          );
+        }
+      }
+    }
+  }
+  async reject(op, reason) {
+    await this.audit.append({
+      event: "rejected",
+      provider: op.provider,
+      tool: op.tool,
+      accountId: op.accountId,
+      summary: reason
+    });
+    throw new AdportError("POLICY_VIOLATION", `Policy violation: ${reason}`, { policy: this.policy });
+  }
+};
+
+// src/tools/write.ts
+import { z as z3 } from "zod";
+var TWO_STEP_NOTE = "Two-step write: call WITHOUT pending_operation_id to get a dry-run preview and a pending_operation_id; call again with IDENTICAL arguments plus that id to apply.";
+function guardedWriteTool(def) {
+  const input = def.payload.extend({
+    account_id: z3.string().min(1).describe("Target account id"),
+    pending_operation_id: z3.string().optional().describe("Omit to get a dry-run preview; pass the returned id to apply.")
+  });
+  return defineTool({
+    name: def.name,
+    namespace: def.namespace,
+    description: `${def.description}
+
+${TWO_STEP_NOTE}`,
+    input,
+    annotations: { readOnly: false, destructive: def.destructive ?? false },
+    async handler(raw, ctx) {
+      const { account_id, pending_operation_id, ...payload } = raw;
+      const provider = ctx.providers.get(def.provider);
+      const op = {
+        tool: def.name,
+        provider: def.provider,
+        accountId: account_id,
+        kind: def.kind,
+        payload
+      };
+      if (!pending_operation_id) {
+        const outcome2 = await ctx.engine.validate(provider, op);
+        return {
+          status: "pending_validation",
+          applied: false,
+          pending_operation_id: outcome2.pendingOperationId,
+          expires_at: outcome2.expiresAt,
+          preview: outcome2.preview,
+          next_step: "Review the preview. To apply, call this tool again with the same arguments plus pending_operation_id."
+        };
+      }
+      const outcome = await ctx.engine.apply(provider, op, pending_operation_id);
+      return { status: "applied", applied: true, result: outcome.result, preview: outcome.preview };
+    }
+  });
+}
+
+// src/tools/builtin.ts
+import { z as z4 } from "zod";
+var dateRangeSchema2 = z4.union([
+  z4.enum(DATE_PRESETS),
+  z4.object({
+    start: z4.string().regex(/^\d{4}-\d{2}-\d{2}$/, "YYYY-MM-DD"),
+    end: z4.string().regex(/^\d{4}-\d{2}-\d{2}$/, "YYYY-MM-DD")
+  })
+]);
+function builtinTools() {
+  return [
+    defineTool({
+      name: "accounts_list",
+      namespace: "core",
+      description: "List connected ad accounts across all providers (or one provider).",
+      input: z4.object({
+        provider: z4.string().optional().describe('Limit to one provider id, e.g. "google".')
+      }),
+      annotations: { readOnly: true },
+      async handler(input, ctx) {
+        const providers = input.provider ? [ctx.providers.get(input.provider)] : ctx.providers.list();
+        const accounts = [];
+        for (const provider of providers) {
+          accounts.push(...await provider.listAccounts());
+        }
+        return { accounts };
+      }
+    }),
+    defineTool({
+      name: "report",
+      namespace: "core",
+      description: "Cross-platform performance report with normalized metrics (spend, clicks, conversions, ROAS, ...). Rows are capped by `limit`; the response says when it truncated.",
+      input: z4.object({
+        provider: z4.string().optional().describe("Limit to one provider id."),
+        account_ids: z4.array(z4.string()).optional(),
+        level: z4.enum(ENTITY_LEVELS).default("campaign"),
+        metrics: z4.array(z4.enum(METRICS)).min(1).default(["spend", "impressions", "clicks", "conversions"]),
+        date_range: dateRangeSchema2.default("last_7_days"),
+        limit: z4.number().int().positive().max(1e3).default(100)
+      }),
+      annotations: { readOnly: true },
+      async handler(input, ctx) {
+        const providers = input.provider ? [ctx.providers.get(input.provider)] : ctx.providers.list();
+        const query = {
+          accountIds: input.account_ids,
+          level: input.level,
+          metrics: input.metrics,
+          dateRange: input.date_range,
+          limit: input.limit
+        };
+        const rows = [];
+        for (const provider of providers) {
+          const report = await provider.report(query);
+          rows.push(...report.rows);
+        }
+        const truncated = rows.length > input.limit;
+        return { rows: rows.slice(0, input.limit), truncated };
+      }
+    })
+  ];
+}
+
+// src/testing/mock-provider.ts
+import { z as z5 } from "zod";
+function seedAccounts() {
+  return [
+    {
+      provider: "mock",
+      id: "mock-1",
+      name: "Acme DTC Store",
+      currency: "EUR",
+      status: "ENABLED",
+      campaigns: [
+        { id: "c1", name: "Brand Search", status: "ENABLED", dailyBudgetMicros: 1e7 },
+        { id: "c2", name: "Prospecting", status: "ENABLED", dailyBudgetMicros: 25e6 },
+        // Deliberately conversion-less: exercises the audit harness.
+        { id: "c4", name: "Legacy Retargeting", status: "ENABLED", dailyBudgetMicros: 8e6 }
+      ]
+    },
+    {
+      provider: "mock",
+      id: "mock-2",
+      name: "Beta App",
+      currency: "USD",
+      status: "ENABLED",
+      campaigns: [{ id: "c3", name: "Install Campaign", status: "PAUSED", dailyBudgetMicros: 5e6 }]
+    }
+  ];
+}
+var MockProvider = class {
+  id = "mock";
+  accounts = seedAccounts();
+  capabilities() {
+    return { serverDryRun: false };
+  }
+  standardActions() {
+    return {
+      pauseCampaign: (accountId, campaignId) => ({
+        tool: "mock_set_campaign_status",
+        input: { account_id: accountId, campaign_id: campaignId, status: "PAUSED" }
+      })
+    };
+  }
+  async listAccounts() {
+    return this.accounts.map(({ campaigns: _campaigns, ...account }) => account);
+  }
+  listCampaigns(accountId) {
+    return [...this.account(accountId).campaigns];
+  }
+  async report(query) {
+    const range = resolveDateRange(query.dateRange);
+    const days = rangeDayCount(range);
+    const rows = [];
+    for (const account of this.accounts) {
+      if (query.accountIds && !query.accountIds.includes(account.id)) continue;
+      for (const [index, campaign] of account.campaigns.entries()) {
+        if (campaign.status === "REMOVED") continue;
+        rows.push({
+          provider: this.id,
+          accountId: account.id,
+          entity: { level: "campaign", id: campaign.id, name: campaign.name, status: campaign.status },
+          metrics: mockMetrics(query.metrics, index, days, campaign.dailyBudgetMicros, campaign.id === "c4")
+        });
+      }
+    }
+    return { rows };
+  }
+  async previewWrite(op, guard) {
+    return this.plan(op, guard).preview;
+  }
+  async applyWrite(op, guard) {
+    return this.plan(op, guard).apply();
+  }
+  account(accountId) {
+    const account = this.accounts.find((a) => a.id === accountId);
+    if (!account) throw new AdportError("PROVIDER_ERROR", `mock: unknown account ${accountId}`);
+    return account;
+  }
+  campaign(accountId, campaignId) {
+    const campaign = this.account(accountId).campaigns.find((c) => c.id === campaignId);
+    if (!campaign) throw new AdportError("PROVIDER_ERROR", `mock: unknown campaign ${campaignId}`);
+    return campaign;
+  }
+  /** Compute preview and applier together so dry-run and apply can never drift. */
+  plan(op, guard) {
+    const base = { coercions: [], budgetDeltas: [], serverValidated: false };
+    switch (op.tool) {
+      case "mock_create_campaign": {
+        const payload = op.payload;
+        let status = payload.status ?? "ENABLED";
+        const coercions = [];
+        if (guard.forcePausedCreation && status === "ENABLED") {
+          status = "PAUSED";
+          coercions.push("status coerced to PAUSED by policy (paused_creation)");
+        }
+        const account = this.account(op.accountId);
+        const id = `c${100 + account.campaigns.length}`;
+        return {
+          preview: {
+            ...base,
+            summary: `Create campaign "${payload.name}" (${status}) with daily budget ${payload.daily_budget_micros} micros`,
+            changes: [`+ campaign ${id} "${payload.name}" status=${status}`],
+            coercions,
+            budgetDeltas: [{ target: `new campaign "${payload.name}" daily budget`, toMicros: payload.daily_budget_micros }]
+          },
+          apply: () => {
+            account.campaigns.push({ id, name: payload.name, status, dailyBudgetMicros: payload.daily_budget_micros });
+            return { applied: true, resourceIds: [id] };
+          }
+        };
+      }
+      case "mock_set_budget": {
+        const payload = op.payload;
+        const campaign = this.campaign(op.accountId, payload.campaign_id);
+        return {
+          preview: {
+            ...base,
+            summary: `Change "${campaign.name}" daily budget ${campaign.dailyBudgetMicros} \u2192 ${payload.daily_budget_micros} micros`,
+            changes: [`~ campaign ${campaign.id} daily_budget ${campaign.dailyBudgetMicros} \u2192 ${payload.daily_budget_micros}`],
+            budgetDeltas: [
+              {
+                target: `campaign "${campaign.name}" daily budget`,
+                fromMicros: campaign.dailyBudgetMicros,
+                toMicros: payload.daily_budget_micros
+              }
+            ]
+          },
+          apply: () => {
+            campaign.dailyBudgetMicros = payload.daily_budget_micros;
+            return { applied: true, resourceIds: [campaign.id] };
+          }
+        };
+      }
+      case "mock_set_campaign_status": {
+        const payload = op.payload;
+        const campaign = this.campaign(op.accountId, payload.campaign_id);
+        return {
+          preview: {
+            ...base,
+            summary: `Set "${campaign.name}" status ${campaign.status} \u2192 ${payload.status}`,
+            changes: [`~ campaign ${campaign.id} status ${campaign.status} \u2192 ${payload.status}`]
+          },
+          apply: () => {
+            campaign.status = payload.status;
+            return { applied: true, resourceIds: [campaign.id] };
+          }
+        };
+      }
+      case "mock_remove_campaign": {
+        const payload = op.payload;
+        const campaign = this.campaign(op.accountId, payload.campaign_id);
+        return {
+          preview: {
+            ...base,
+            summary: `PERMANENTLY remove campaign "${campaign.name}"`,
+            changes: [`- campaign ${campaign.id} "${campaign.name}"`]
+          },
+          apply: () => {
+            campaign.status = "REMOVED";
+            return { applied: true, resourceIds: [campaign.id] };
+          }
+        };
+      }
+      default:
+        throw new AdportError("PROVIDER_ERROR", `mock: unsupported write tool ${op.tool}`);
+    }
+  }
+};
+function mockMetrics(requested, seed, days, dailyBudgetMicros, zeroConversions = false) {
+  const spend = (dailyBudgetMicros / 1e6 * 0.83 + seed) * days;
+  const impressions = (2e3 + seed * 700) * days;
+  const clicks = (90 + seed * 35) * days;
+  const conversions = zeroConversions ? 0 : (4 + seed) * days;
+  const conversionValue = conversions * (35 + seed * 5);
+  const all = {
+    spend: round2(spend),
+    impressions,
+    clicks,
+    conversions,
+    conversion_value: round2(conversionValue),
+    ctr: round2(clicks / impressions * 100),
+    cpc: round2(spend / clicks),
+    cpm: round2(spend / impressions * 1e3),
+    cpa: conversions > 0 ? round2(spend / conversions) : 0,
+    roas: spend > 0 ? round2(conversionValue / spend) : 0
+  };
+  return Object.fromEntries(requested.map((m) => [m, all[m]]));
+}
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+function mockTools() {
+  return [
+    defineTool({
+      name: "mock_list_campaigns",
+      namespace: "mock",
+      description: "List campaigns in a mock account (id, name, status, daily budget).",
+      input: z5.object({ account_id: z5.string() }),
+      annotations: { readOnly: true },
+      async handler(input, ctx) {
+        const provider = ctx.providers.get("mock");
+        return { campaigns: provider.listCampaigns(input.account_id) };
+      }
+    }),
+    guardedWriteTool({
+      name: "mock_create_campaign",
+      namespace: "mock",
+      description: "Create a campaign in the mock account.",
+      provider: "mock",
+      kind: "create",
+      payload: z5.object({
+        name: z5.string().min(1),
+        daily_budget_micros: z5.number().int().positive(),
+        status: z5.enum(["ENABLED", "PAUSED"]).optional()
+      })
+    }),
+    guardedWriteTool({
+      name: "mock_set_budget",
+      namespace: "mock",
+      description: "Change a mock campaign daily budget.",
+      provider: "mock",
+      kind: "update",
+      payload: z5.object({ campaign_id: z5.string(), daily_budget_micros: z5.number().int().positive() })
+    }),
+    guardedWriteTool({
+      name: "mock_set_campaign_status",
+      namespace: "mock",
+      description: "Enable or pause a mock campaign.",
+      provider: "mock",
+      kind: "update",
+      payload: z5.object({ campaign_id: z5.string(), status: z5.enum(["ENABLED", "PAUSED"]) })
+    }),
+    guardedWriteTool({
+      name: "mock_remove_campaign",
+      namespace: "mock",
+      description: "Permanently remove a mock campaign.",
+      provider: "mock",
+      kind: "remove",
+      destructive: true,
+      payload: z5.object({ campaign_id: z5.string() })
+    })
+  ];
+}
+
+// src/context.ts
+async function createContext(options = {}) {
+  const modules = options.providerModules ?? [];
+  const includeMock = options.includeMock ?? modules.length === 0;
+  const providers = new ProviderRegistry();
+  const { policy, source } = await loadPolicy(options.policyPath);
+  const engine = new PolicyEngine(policy);
+  const credentials = new CredentialStore();
+  const registry = new ToolRegistry();
+  registry.register(builtinTools());
+  registry.register(auditTools());
+  for (const module of modules) {
+    providers.register(module.provider);
+    registry.register(module.tools);
+  }
+  if (includeMock) {
+    providers.register(new MockProvider());
+    registry.register(mockTools());
+  }
+  const ctx = { providers, engine, credentials };
+  ctx.registry = registry;
+  return { ctx, registry, policySource: source };
+}
+export {
+  AdportError,
+  AuditLog,
+  AuditRunner,
+  CredentialStore,
+  DATE_PRESETS,
+  DEFAULT_POLICY,
+  ENTITY_LEVELS,
+  FindingsStore,
+  METRICS,
+  MockProvider,
+  PendingStore,
+  PolicyEngine,
+  ProviderRegistry,
+  ToolRegistry,
+  adportHome,
+  auditTools,
+  builtinTools,
+  corePerformancePack,
+  createContext,
+  defineTool,
+  guardedWriteTool,
+  hashOperation,
+  loadPolicy,
+  mockTools,
+  policySchema,
+  rangeDayCount,
+  resolveDateRange
+};
+//# sourceMappingURL=index.js.map