@twin3-ai/agent-id 0.2.0 → 0.3.0

package/b1-sync.js

@@ -0,0 +1,85 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const GA4_ENDPOINT = "https://analyticsdata.googleapis.com/v1beta/properties";
+const AI_HOSTS = Object.freeze(["chat.openai.com", "chatgpt.com", "claude.ai", "copilot.microsoft.com", "gemini.google.com", "perplexity.ai"]);
+
+function hash(value) { return crypto.createHash("sha256").update(String(value)).digest("hex"); }
+function emptyState() { return { schema: "agentx-b1-sync-state-v1", cursor: "", pending: null, seen: [], retry_at: 0, attempts: 0, next_run_at: 0, last_sync_at: 0, last_error: null }; }
+function loadState(statePath) {
+  try { return { ...emptyState(), ...JSON.parse(fs.readFileSync(statePath, "utf8")) }; }
+  catch (error) { if (error.code === "ENOENT") return emptyState(); throw new Error("b1_sync_state_invalid"); }
+}
+function saveState(statePath, state) {
+  const target = path.resolve(statePath); fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try { fs.writeFileSync(temporary, JSON.stringify(state, null, 2) + "\n", { mode:0o600, flag:"wx" }); fs.renameSync(temporary, target); fs.chmodSync(target, 0o600); }
+  finally { try { fs.rmSync(temporary, { force:true }); } catch (_error) {} }
+}
+function aiHost(value) {
+  const raw = String(value || "").trim().toLowerCase();
+  if (!raw || ["(direct)", "(none)", "(not set)"].includes(raw)) return "";
+  try {
+    const host = new URL(raw.includes("://") ? raw : `https://${raw}`).hostname.replace(/\.$/, "");
+    return AI_HOSTS.find((known) => host === known || host.endsWith(`.${known}`)) ? host : "";
+  } catch (_error) { return ""; }
+}
+function safeLabel(value) { return /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(String(value || "")) ? String(value) : ""; }
+function reportMap(row, dimensionHeaders, metricHeaders) {
+  const dimensions = Object.fromEntries(dimensionHeaders.map((name, index) => [name, String(row.dimensionValues && row.dimensionValues[index] && row.dimensionValues[index].value || "")]));
+  const metrics = Object.fromEntries(metricHeaders.map((name, index) => [name, String(row.metricValues && row.metricValues[index] && row.metricValues[index].value || "0")]));
+  return { dimensions, metrics };
+}
+function ga4Conversions(response, siteUrl, windowKey) {
+  const dimensions = (response.dimensionHeaders || []).map((item) => item && item.name).filter(Boolean);
+  const metrics = (response.metricHeaders || []).map((item) => item && item.name).filter(Boolean);
+  return (response.rows || []).flatMap((row) => {
+    const mapped = reportMap(row || {}, dimensions, metrics);
+    const source = aiHost(mapped.dimensions.sessionSource);
+    const count = Math.max(0, Math.floor(Number(mapped.metrics.keyEvents || 0)));
+    const revenue = Math.max(0, Number(mapped.metrics.totalRevenue || 0));
+    if (!source || count < 1 || !Number.isFinite(revenue)) return [];
+    const campaign = safeLabel(mapped.dimensions.sessionCampaignName);
+    const currency = String(response.currencyCode || response.metadata && response.metadata.currencyCode || "USD").toUpperCase();
+    return [{ conversion_id:`ga4_${hash(JSON.stringify([windowKey, source, campaign])).slice(0,32)}`, event:"ga4_key_event", url:siteUrl, referrer:`https://${source}/`, utm_source:source, utm_campaign:campaign, conversion_count:count, value:Number(revenue.toFixed(2)), currency:/^[A-Z]{3}$/.test(currency)?currency:"USD", timestamp:Date.parse(`${windowKey}T23:59:59Z`) }];
+  });
+}
+async function defaultFetchGa4({ token, propertyId, startDate, endDate, fetchImpl = globalThis.fetch }) {
+  if (typeof fetchImpl !== "function") throw new Error("ga4_fetch_unavailable");
+  const response = await fetchImpl(`${GA4_ENDPOINT}/${encodeURIComponent(propertyId)}:runReport`, { method:"POST", headers:{ authorization:`Bearer ${token}`, "content-type":"application/json" }, body:JSON.stringify({ dateRanges:[{startDate,endDate}], dimensions:[{name:"sessionSource"},{name:"sessionMedium"},{name:"sessionCampaignName"}], metrics:[{name:"sessions"},{name:"keyEvents"},{name:"totalRevenue"}] }), redirect:"error" });
+  if (!response.ok) throw new Error(`ga4_http_${response.status}`);
+  const body = await response.json(); if (body.error) throw new Error("ga4_provider_error"); return body;
+}
+function createBaseSync({ client, statePath, siteUrl, intervalMs, collect, now, random }) {
+  if (!client || typeof client.conversions !== "function" || !statePath || !siteUrl || typeof collect !== "function") throw new Error("b1_sync_configuration_invalid");
+  const url = new URL(siteUrl).origin; const state = loadState(statePath); const persist = () => saveState(statePath, state);
+  async function upload(batch, cursor) {
+    try {
+      const result = batch.length ? await client.conversions({ url, conversions:batch, source:"b1_automatic_sync" }) : { stored:0 };
+      state.pending=null; state.cursor=cursor; state.seen=[...new Set([...state.seen,...batch.map(item=>item.conversion_id)])].slice(-10000); state.retry_at=0; state.attempts=0; state.last_sync_at=now(); state.next_run_at=state.last_sync_at+Math.max(60000,intervalMs); state.last_error=null; persist();
+      return {ok:true,status:"synced",rows:batch.length,conversions:batch.reduce((sum,item)=>sum+Math.max(1,Number(item.conversion_count||1)),0),stored:Number(result.stored||0),cursor};
+    } catch (error) {
+      state.pending={batch:batch.slice(0,5000),cursor}; state.attempts+=1; const backoff=Math.min(300000,1000*(2**Math.min(8,state.attempts-1))); state.retry_at=now()+Math.round(backoff*(0.5+random())); state.last_error={code:String(error.code||"b1_delivery_failed").slice(0,80)}; persist();
+      return {ok:false,status:"queued_for_retry",pending:state.pending.batch.length,retry_at:state.retry_at};
+    }
+  }
+  async function runOnce({force=false}={}) {
+    const timestamp=now(); if(!force&&state.retry_at>timestamp)return {ok:false,status:"retry_wait",retry_at:state.retry_at}; if(state.pending)return upload(state.pending.batch,state.pending.cursor); if(!force&&state.next_run_at>timestamp)return {ok:true,status:"not_due",next_run_at:state.next_run_at};
+    const collected=await collect({timestamp,cursor:state.cursor,seen:new Set(state.seen)}); return upload(collected.batch||[],collected.cursor||state.cursor);
+  }
+  async function status(){return {schema:state.schema,host:new URL(url).hostname,cursor:state.cursor,pending:state.pending?state.pending.batch.length:0,retry_at:state.retry_at,next_run_at:state.next_run_at,last_sync_at:state.last_sync_at,last_error:state.last_error};}
+  return Object.freeze({runOnce,status});
+}
+function createGa4B1Sync({client,statePath,siteUrl,propertyId,accessToken,fetchGa4=defaultFetchGa4,intervalMs=86400000,now=Date.now,random=Math.random}={}) {
+  if(!propertyId||!accessToken)throw new Error("ga4_b1_configuration_invalid");
+  return createBaseSync({client,statePath,siteUrl,intervalMs,now,random,collect:async({timestamp,cursor})=>{const date=new Date(timestamp-86400000).toISOString().slice(0,10);if(cursor===date)return {batch:[],cursor};const response=await fetchGa4({token:accessToken,propertyId,startDate:date,endDate:date});return {batch:ga4Conversions(response,new URL(siteUrl).origin,date),cursor:date};}});
+}
+function createOrderB1Sync({client,statePath,siteUrl,sourceId,loadOrders,intervalMs=3600000,now=Date.now,random=Math.random}={}) {
+  if(!safeLabel(sourceId)||typeof loadOrders!=="function")throw new Error("order_b1_configuration_invalid");
+  return createBaseSync({client,statePath,siteUrl,intervalMs,now,random,collect:async({timestamp,seen})=>{const rows=await loadOrders();const batch=(Array.isArray(rows)?rows:[]).flatMap((row)=>{const source=aiHost(row&&row.source);const rawId=String(row&&row.order_id||"");const receipt=rawId?`order_${hash(`${sourceId}:${rawId}`).slice(0,32)}`:"";const amount=Number(row&&row.amount||0);if(!source||!receipt||seen.has(receipt)||!Number.isFinite(amount)||amount<0)return [];return [{conversion_id:receipt,event:safeLabel(row.event)||"order",url:new URL(siteUrl).origin,referrer:`https://${source}/`,value:Number(amount.toFixed(2)),currency:/^[A-Z]{3}$/.test(String(row.currency||"").toUpperCase())?String(row.currency).toUpperCase():"USD",timestamp:Number(row.timestamp||timestamp)}];});return {batch,cursor:String(timestamp)};}});
+}
+
+module.exports={createGa4B1Sync,createOrderB1Sync,ga4Conversions,defaultFetchGa4};

package/bin/agent-id-b1-sync.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { createSiteAgentClient } = require("../site-agent.js");
+const { createGa4B1Sync, createOrderB1Sync } = require("../b1-sync.js");
+
+function valueAfter(args, name, fallback = "") { const index=args.indexOf(name); return index>=0&&args[index+1]?args[index+1]:fallback; }
+function help() {
+  console.log(`agent-id-b1-sync
+
+Usage:
+  agent-id-b1-sync --ga4 --url https://example.com
+  agent-id-b1-sync --orders ./crm-orders.json --source-id crm-main --url https://example.com
+
+Shared environment:
+  SITE_AGENT_KEY       Agent ID Site Agent Key
+  AGENT_ID_ENDPOINT    Parent Agent ID origin
+  AGENT_ID_B1_STATE    Local cursor and retry state path
+
+GA4 environment:
+  GA4_PROPERTY_ID      GA4 numeric property ID
+  GA4_ACCESS_TOKEN     Read-only Analytics Data API OAuth token
+`);
+}
+async function main() {
+  const args=process.argv.slice(2); if(args.includes("--help")||args.includes("-h"))return help();
+  const siteUrl=valueAfter(args,"--url",process.env.SITE_URL||""); if(!siteUrl)throw new Error("--url or SITE_URL is required");
+  const endpoint=valueAfter(args,"--endpoint",process.env.AGENT_ID_ENDPOINT||"");
+  const statePath=valueAfter(args,"--state",process.env.AGENT_ID_B1_STATE||path.join(process.cwd(),".agent-id","b1-sync-state.json"));
+  const client=createSiteAgentClient({endpoint,agentKey:process.env.SITE_AGENT_KEY});
+  let sync;
+  if(args.includes("--ga4")) {
+    sync=createGa4B1Sync({client,statePath,siteUrl,propertyId:process.env.GA4_PROPERTY_ID,accessToken:process.env.GA4_ACCESS_TOKEN});
+  } else {
+    const orderPath=valueAfter(args,"--orders",""); const sourceId=valueAfter(args,"--source-id","");
+    if(!orderPath||!sourceId)throw new Error("--ga4 or both --orders and --source-id are required");
+    sync=createOrderB1Sync({client,statePath,siteUrl,sourceId,loadOrders:async()=>JSON.parse(fs.readFileSync(path.resolve(orderPath),"utf8"))});
+  }
+  const result=args.includes("--status")?await sync.status():await sync.runOnce({force:args.includes("--force")});
+  console.log(JSON.stringify(result,null,2));
+}
+main().catch((error)=>{console.error(error&&error.message?error.message:"b1_sync_failed");process.exit(1);});

package/bin/agent-id-cloudflare-a1.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("node:path");
+const { createSiteAgentClient } = require("../site-agent.js");
+const { createCloudflareA1Sync } = require("../cloudflare-a1-sync.js");
+
+function valueAfter(args, name, fallback = "") {
+  const index = args.indexOf(name);
+  return index >= 0 && args[index + 1] ? args[index + 1] : fallback;
+}
+function help() {
+  console.log(`agent-id-cloudflare-a1
+
+Usage:
+  agent-id-cloudflare-a1 --url https://example.com --once
+  agent-id-cloudflare-a1 --url https://example.com --status
+
+Required environment:
+  SITE_AGENT_KEY          Agent ID Site Agent Key
+  CLOUDFLARE_API_TOKEN    Read-only Cloudflare Analytics token
+  CLOUDFLARE_ZONE_ID      Website zone ID
+
+Optional environment:
+  AGENT_ID_ENDPOINT       Parent Agent ID origin
+  AGENT_ID_A1_STATE       Local cursor and retry state path
+  AGENT_ID_A1_INTERVAL_MS Minimum interval between successful syncs
+`);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) return help();
+  const siteUrl = valueAfter(args, "--url", process.env.SITE_URL || "");
+  const endpoint = valueAfter(args, "--endpoint", process.env.AGENT_ID_ENDPOINT || "");
+  const statePath = valueAfter(args, "--state", process.env.AGENT_ID_A1_STATE || path.join(process.cwd(), ".agent-id", "cloudflare-a1-state.json"));
+  if (!siteUrl) throw new Error("--url or SITE_URL is required");
+  const client = createSiteAgentClient({ endpoint, agentKey: process.env.SITE_AGENT_KEY });
+  const sync = createCloudflareA1Sync({
+    client,
+    statePath,
+    siteUrl,
+    zoneId: process.env.CLOUDFLARE_ZONE_ID,
+    apiToken: process.env.CLOUDFLARE_API_TOKEN,
+    intervalMs: Number(process.env.AGENT_ID_A1_INTERVAL_MS || 900000)
+  });
+  const result = args.includes("--status") ? await sync.status() : await sync.runOnce({ force: args.includes("--force") });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+main().catch((error) => {
+  console.error(error && error.message ? error.message : "cloudflare_a1_sync_failed");
+  process.exit(1);
+});