@analitikisler/ai-tag-debugger 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.11.2 (2026-10-16)
+
+- Fix sentence requests (`aitd "check my GA tags"`) failing with a 400 "Invalid schema" error from the Anthropic API. The request schema now writes optional values in a form Anthropic, OpenAI and Gemini all accept.
+- When `AI_GATEWAY_URL` is set, the first line of a run says so: `Using anthropic (claude-opus-5-5) via Cloudflare AI Gateway`.
+
+## 0.11.1 (2026-10-16)
+
+- Set `AI_GATEWAY_URL` (and `AI_GATEWAY_TOKEN` if the gateway has authentication on) to send Anthropic, OpenAI and Gemini calls through Cloudflare AI Gateway, for logs and cost tracking. Unset, nothing changes.
+
 ## 0.11.0 (2026-10-16)
 
 - Every saved run is compared with the site's previous run. The report opens with a "Changed since last run" section (`2 events fixed, 1 new problem`) that lists what was fixed and what is new, by plan coverage when both runs used `--against` and by health findings otherwise. The first run says there is nothing to compare yet. No new flag; the result is also in `capture.json` under `changes`.

package/README.md

@@ -99,6 +99,17 @@ ai-tag-debugger run --site https://yourshop.com --journey add_to_cart \
 
 Use the model id from your provider's documentation. You can also set `OPENAI_COMPATIBLE_BASE_URL` and `OPENAI_COMPATIBLE_MODEL` instead of the flags, or `"provider"`, `"base_url"` and `"model"` in the config. When the API can't return strict JSON schemas, the explanations fall back to plain JSON mode.
 
+### Cloudflare AI Gateway
+
+To see logs, costs and rate limits for every AI call, send them through [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/). Your provider key stays the same:
+
+```bash
+export AI_GATEWAY_URL=https://gateway.ai.cloudflare.com/v1/<account id>/default
+export AI_GATEWAY_TOKEN=...   # only if the gateway has authentication on
+```
+
+This works with `anthropic`, `openai` and `gemini`. Leave caching off in the gateway so each run sees your live site. Cloudflare Workers AI models also work through the OpenAI-compatible provider, with `--base-url https://api.cloudflare.com/client/v4/accounts/<account id>/ai/v1`.
+
 **A word on model choice.** The AI browses by calling tools, one step at a time, for 5 to 30 steps. Models differ a lot in how reliably they do that: smaller and local models may click the wrong thing, loop, or stop early. The checks stay correct whatever the model does, because they come from the captured hits, but a journey that doesn't finish can't show its later events. If a model struggles, try a larger one, a ready-made journey with a short goal, or `--max-steps`. The Anthropic, OpenAI and Gemini defaults are the tested ones.
 
 Adding a native provider means implementing two functions in [`src/providers.js`](src/providers.js): a tool-calling conversation and a structured JSON call.

package/README.tr.md

@@ -99,6 +99,17 @@ ai-tag-debugger run --site https://yourshop.com --journey add_to_cart \
 
 Model kimliğini sağlayıcınızın dokümantasyonundan alın. Bayrakların yerine `OPENAI_COMPATIBLE_BASE_URL` ve `OPENAI_COMPATIBLE_MODEL` değişkenlerini ya da ayar dosyasında `"provider"`, `"base_url"` ve `"model"` alanlarını da kullanabilirsiniz. API katı JSON şemalarını döndüremezse açıklamalar düz JSON moduna geçer.
 
+### Cloudflare AI Gateway
+
+Her AI çağrısının kayıtlarını, maliyetini ve limitlerini görmek için çağrıları [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/) üzerinden gönderin. Sağlayıcı anahtarınız aynı kalır:
+
+```bash
+export AI_GATEWAY_URL=https://gateway.ai.cloudflare.com/v1/<hesap kimliği>/default
+export AI_GATEWAY_TOKEN=...   # yalnızca gateway'de kimlik doğrulama açıksa
+```
+
+`anthropic`, `openai` ve `gemini` ile çalışır. Her çalıştırmanın canlı sitenizi görmesi için gateway'de önbelleği kapalı bırakın. Cloudflare Workers AI modelleri de OpenAI uyumlu sağlayıcıyla `--base-url https://api.cloudflare.com/client/v4/accounts/<hesap kimliği>/ai/v1` kullanılarak çalışır.
+
 **Model seçimi hakkında bir not.** Yapay zekâ, 5 ila 30 adım boyunca araç çağırarak, her seferinde bir adım gezinir. Modeller bunu ne kadar güvenilir yaptıklarında büyük farklılık gösterir: daha küçük ve yerel modeller yanlış yere tıklayabilir, döngüye girebilir ya da erken durabilir. Kontroller model ne yaparsa yapsın doğrudur, çünkü yakalanan isteklerden gelirler; ama bitmeyen bir yolculuk, sonraki event'lerini gösteremez. Bir model zorlanıyorsa daha büyük bir model, kısa hedefli hazır bir yolculuk ya da `--max-steps` deneyin. Anthropic, OpenAI ve Gemini varsayılanları test edilmiş olanlardır.
 
 Yerel bir sağlayıcı eklemek için [`src/providers.js`](src/providers.js) içinde iki fonksiyon yazmanız gerekir: araç çağıran bir konuşma ve yapılandırılmış bir JSON çağrısı.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@analitikisler/ai-tag-debugger",
   "mcpName": "io.github.analitikisler/ai-tag-debugger",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Open-source AI agent that QA-tests your website's analytics, ad and consent tracking (GA4, GTM, Google Ads, Meta, TikTok). Bring your own model (Claude, OpenAI, Gemini) or use it from your chat app over MCP.",
   "type": "module",
   "bin": {

package/src/ask.js

@@ -7,19 +7,21 @@ const PLATFORM_KEYS = Object.keys(PLATFORMS);
 // The same values as plan --topic (TOPICS in discover.js, kept in step by a test).
 export const TOPIC_KEYS = ["custom-events", "ecommerce", "forms", "consent"];
 
+// Optional values use anyOf with a null branch, not type: ["string", "null"]: the Anthropic API
+// rejects an enum next to a type list, and anyOf works for OpenAI and Gemini too.
 export const INTENT_SCHEMA = {
   type: "object",
   additionalProperties: false,
   required: ["action", "site", "against", "platforms", "goal", "journey", "topic", "question"],
   properties: {
     action: { type: "string", enum: ["plan", "run", "report", "unclear"], description: "plan drafts what a site should track; run audits what the site sends; report re-reads an existing report; unclear when you cannot tell plan from run." },
-    site: { type: ["string", "null"], description: "The site's domain or URL if the sentence names one." },
-    against: { type: ["string", "null"], enum: ["plan", "latest", null], description: "run only: compare with the saved plan, or with the latest run (\"what changed\", \"since the last run\", \"after the deploy\")." },
+    site: { anyOf: [{ type: "string" }, { type: "null" }], description: "The site's domain or URL if the sentence names one." },
+    against: { anyOf: [{ type: "string", enum: ["plan", "latest"] }, { type: "null" }], description: "run only: compare with the saved plan, or with the latest run (\"what changed\", \"since the last run\", \"after the deploy\")." },
     platforms: { type: "array", items: { type: "string", enum: PLATFORM_KEYS }, description: "Only the tracking platforms the sentence names; empty for all." },
-    goal: { type: ["string", "null"], description: "run only: a short user journey to try, in plain words, e.g. \"submit the contact form\"." },
-    journey: { type: ["string", "null"], enum: ["purchase", null], description: "run only: purchase when the sentence is about the purchase event or revenue." },
-    topic: { type: ["string", "null"], enum: [...TOPIC_KEYS, null], description: "plan only: limit the plan to one kind of event when the sentence asks about it." },
-    question: { type: ["string", "null"], description: "One short question to ask back when the sentence is ambiguous; otherwise null." },
+    goal: { anyOf: [{ type: "string" }, { type: "null" }], description: "run only: a short user journey to try, in plain words, e.g. \"submit the contact form\"." },
+    journey: { anyOf: [{ type: "string", enum: ["purchase"] }, { type: "null" }], description: "run only: purchase when the sentence is about the purchase event or revenue." },
+    topic: { anyOf: [{ type: "string", enum: TOPIC_KEYS }, { type: "null" }], description: "plan only: limit the plan to one kind of event when the sentence asks about it." },
+    question: { anyOf: [{ type: "string" }, { type: "null" }], description: "One short question to ask back when the sentence is ambiguous; otherwise null." },
   },
 };
 

package/src/audit.js

@@ -102,7 +102,7 @@ export async function runAudit(opts) {
   }
 
   const provider = useAi ? await createProvider({ name: opts.provider ?? config.provider, model: opts.model ?? config.model, baseUrl: opts.baseUrl ?? config.base_url }) : null;
-  if (provider) log(`Using ${provider.name} (${provider.model})`);
+  if (provider) log(`Using ${provider.name} (${provider.model})${provider.via ? ` via ${provider.via}` : ""}`);
 
   if (opts.saveSite) await mkdir(opts.saveSite, { recursive: true });
   const runs = [];

package/src/providers.js

@@ -57,11 +57,36 @@ export async function createProvider(opts = {}, env = process.env) {
     return openaiProvider(client, model, { compatible: true, label: new URL(baseURL).host });
   }
   const model = opts.model ?? PROVIDERS[name].defaultModel;
-  if (name === "anthropic") return anthropicProvider(opts.client ?? new (await import("@anthropic-ai/sdk")).default(), model);
-  if (name === "openai") return openaiProvider(opts.client ?? new (await import("openai")).default(), model);
+  const gateway = gatewayOptions(name, env);
+  const provider = await builtInProvider(name, model, gateway, opts.client, env);
+  // Shown in the "Using ..." line so a run says whether its calls went through the gateway.
+  if (gateway.baseURL && !opts.client) provider.via = "Cloudflare AI Gateway";
+  return provider;
+}
+
+async function builtInProvider(name, model, gateway, client, env) {
+  if (name === "anthropic") return anthropicProvider(client ?? new (await import("@anthropic-ai/sdk")).default(gateway), model);
+  if (name === "openai") return openaiProvider(client ?? new (await import("openai")).default(gateway), model);
   const { GoogleGenAI } = await import("@google/genai");
   const apiKey = env.GEMINI_API_KEY ?? env.GOOGLE_API_KEY;
-  return geminiProvider(opts.client ?? new GoogleGenAI(apiKey ? { apiKey } : {}), model);
+  const httpOptions = gateway.baseURL ? { httpOptions: { baseUrl: gateway.baseURL, headers: gateway.defaultHeaders } } : {};
+  return geminiProvider(client ?? new GoogleGenAI({ ...(apiKey ? { apiKey } : {}), ...httpOptions }), model);
+}
+
+// Cloudflare AI Gateway path for each provider, appended to AI_GATEWAY_URL.
+const GATEWAY_PATHS = { anthropic: "anthropic", openai: "openai", gemini: "google-ai-studio" };
+
+/**
+ * SDK client options that send a provider's calls through Cloudflare AI Gateway, for logs,
+ * cost tracking and optional caching. AI_GATEWAY_URL is https://gateway.ai.cloudflare.com/v1/<account>/<gateway>;
+ * AI_GATEWAY_TOKEN is only needed when the gateway has authentication on. Empty when unset.
+ */
+export function gatewayOptions(name, env = process.env) {
+  const base = env.AI_GATEWAY_URL?.trim().replace(/\/+$/, "");
+  if (!base || !GATEWAY_PATHS[name]) return {};
+  const options = { baseURL: `${base}/${GATEWAY_PATHS[name]}` };
+  if (env.AI_GATEWAY_TOKEN) options.defaultHeaders = { "cf-aig-authorization": `Bearer ${env.AI_GATEWAY_TOKEN}` };
+  return options;
 }
 
 // --- Anthropic ---------------------------------------------------------------