@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-lead-measurement/scripts/delivery-v2.mjs

@@ -0,0 +1,234 @@
+import { resolveConsent } from "./consent.mjs";
+import {
+  canonical,
+  classify,
+  clone,
+  deliveryKey,
+  digest,
+  eventProjection,
+  fail,
+  fields,
+  freeze,
+  integer,
+  scope,
+} from "./delivery-v2-contract.mjs";
+
+const purposes = Object.freeze({
+  meta_capi: "meta_measurement",
+  ga4_mp: "analytics",
+  kommo: "contact",
+});
+export function createDeliveryV2(options) {
+  fields(options, ["destinations", "readCurrent"]);
+  if (typeof options.readCurrent !== "function") fail("reader_required");
+  const readCurrent = options.readCurrent;
+  // canonical checks descriptors before reading an array entry.
+  const declared = clone(options.destinations);
+  if (!Array.isArray(declared) || !declared.length || declared.length > 30)
+    fail("invalid_manifest");
+  const targets = new Map(),
+    physical = new Set();
+  for (const input of declared) {
+    const target = scope(input);
+    if (targets.has(target.destination_id) || physical.has(deliveryKey(target, "manifest")))
+      fail("duplicate_destination");
+    targets.set(target.destination_id, target);
+    physical.add(deliveryKey(target, "manifest"));
+  }
+  const jobs = new Map(),
+    facts = new Map(),
+    watermarks = new Map();
+  let serial = 0;
+  const snapshot = (job) => freeze(clone(job));
+  const find = (key) => {
+    if (typeof key !== "string" || !jobs.has(key)) fail("unknown_delivery");
+    return jobs.get(key);
+  };
+  function eligible(job) {
+    try {
+      const current = resolveConsent(readCurrent(snapshot(job.scope), job.event_id));
+      const context = canonical([job.scope.tenant, job.scope.environment, job.event_id]);
+      const previous = watermarks.get(context);
+      const signature = canonical(current.history);
+      if (
+        previous &&
+        (current.revision < previous.revision ||
+          (current.revision === previous.revision && signature !== previous.signature))
+      )
+        return false;
+      watermarks.set(context, { revision: current.revision, signature });
+      return current.states[purposes[job.scope.provider]] === "granted"; // MUT_CONSENT
+    } catch {
+      return false;
+    }
+  }
+  function invalidate(job, state) {
+    job.state = state;
+    job.fence++;
+    job.lease = null;
+    job.lease_until = null;
+    job.started = false;
+  }
+  function leased(key, token, at) {
+    integer(at, 0, Number.MAX_SAFE_INTEGER);
+    fields(token, ["id", "fence"]);
+    const job = find(key);
+    if (
+      job.state !== "leased" ||
+      job.lease !== token.id ||
+      job.fence !== token.fence ||
+      job.lease_until <= at
+    )
+      fail("stale_lease"); // MUT_FENCE
+    return job;
+  }
+  return Object.freeze({
+    model_only: true, // MUT_MODEL
+    enqueue(destinationId, event, config) {
+      if (typeof destinationId !== "string" || !targets.has(destinationId))
+        fail("unapproved_destination");
+      const target = targets.get(destinationId);
+      const projected = eventProjection(event, config, target.provider);
+      const key = deliveryKey(target, projected.event.event_id);
+      const fact = canonical([
+        target.tenant,
+        target.environment,
+        target.mode,
+        projected.event.event_id,
+      ]);
+      const eventDigest = digest(projected.event);
+      if (facts.has(fact) && facts.get(fact) !== eventDigest) fail("event_conflict");
+      if (jobs.has(key)) {
+        const prior = jobs.get(key);
+        if (
+          prior.fingerprint !== projected.fingerprint ||
+          prior.scope.destination_id !== destinationId
+        )
+          fail("delivery_conflict");
+        return { key, status: "replay", job: snapshot(prior) };
+      }
+      const job = {
+        schema_version: 2,
+        scope: target,
+        event_id: projected.event.event_id,
+        fingerprint: projected.fingerprint,
+        mapping_version: projected.config.mapping_version,
+        payload: projected.payload,
+        policy: projected.config.retry,
+        state: "pending",
+        attempts: 0,
+        available_at: 0,
+        fence: 0,
+        lease: null,
+        lease_until: null,
+        started: false,
+        transport: null,
+        semantic_acceptance: "unverified",
+        confirmed: false,
+        attributed: false,
+      };
+      facts.set(fact, eventDigest);
+      jobs.set(key, job);
+      return { key, status: "queued", job: snapshot(job) };
+    },
+    get(key) {
+      return snapshot(find(key));
+    },
+    claim(key, at, duration = 1000) {
+      integer(at, 0, Number.MAX_SAFE_INTEGER);
+      integer(duration, 1, 300000);
+      if (!Number.isSafeInteger(at + duration)) fail("clock_overflow");
+      const job = find(key);
+      if (job.state === "leased") {
+        if (job.lease_until > at) return { allowed: false, reason: "busy" };
+        invalidate(job, "uncertain");
+      }
+      if (!["pending", "retry"].includes(job.state))
+        return { allowed: false, reason: "reconciliation_or_terminal" };
+      if (at < job.available_at) return { allowed: false, reason: "not_due" };
+      if (job.attempts >= job.policy.max_attempts) {
+        job.state = "terminal";
+        return { allowed: false, reason: "exhausted" };
+      }
+      if (!eligible(job)) return { allowed: false, reason: "consent_ineligible" };
+      job.state = "leased";
+      job.fence++;
+      job.lease = `lease_${++serial}`;
+      job.lease_until = at + duration;
+      job.started = false;
+      return freeze({ allowed: true, token: { id: job.lease, fence: job.fence } });
+    },
+    authorize(key, token, at, effect) {
+      if (typeof effect !== "function") fail("effect_required");
+      const job = leased(key, token, at);
+      if (job.started) fail("already_started");
+      if (!eligible(job)) return { allowed: false, reason: "consent_ineligible" };
+      job.started = true;
+      job.attempts++;
+      try {
+        effect(freeze(clone(job.payload)));
+      } catch {
+        invalidate(job, "uncertain");
+        return { allowed: false, reason: "effect_uncertain" };
+      }
+      return { allowed: true, model_only: true };
+    },
+    record(key, token, response, at, jitter = 0) {
+      const job = leased(key, token, at);
+      if (!job.started) fail("attempt_not_started");
+      if (typeof jitter !== "number" || !Number.isFinite(jitter) || jitter < 0 || jitter > 1)
+        fail("invalid_jitter");
+      let result;
+      try {
+        result = classify(job.scope.provider, response);
+      } catch {
+        invalidate(job, "uncertain");
+        job.semantic_acceptance = "rejected";
+        return snapshot(job);
+      }
+      job.transport = result.transport;
+      job.semantic_acceptance = result.semantic;
+      if (result.state === "retry") {
+        if (job.attempts >= job.policy.max_attempts)
+          result.state = "terminal"; // MUT_EXHAUSTION
+        else if (result.retry_after_ms > job.policy.max_delay_ms) result.state = "uncertain";
+        else {
+          const base = Math.min(
+            job.policy.max_delay_ms,
+            job.policy.base_delay_ms * 2 ** (job.attempts - 1),
+          );
+          const delay = Math.max(
+            result.retry_after_ms,
+            Math.min(job.policy.max_delay_ms, base + Math.floor(base * 0.25 * jitter)),
+          ); // MUT_RETRY
+          if (!Number.isSafeInteger(at + delay)) fail("clock_overflow");
+          job.available_at = at + delay;
+        }
+      }
+      job.confirmed = result.state === "confirmed";
+      invalidate(job, result.state);
+      return snapshot(job);
+    },
+    reconcile(key, proof, at) {
+      fields(proof, ["decision", "reference"]);
+      if (
+        !["confirmed_effect", "absent_effect"].includes(proof.decision) ||
+        typeof proof.reference !== "string" ||
+        !/^[a-z][a-z0-9_]{0,63}$/.test(proof.reference)
+      )
+        fail("invalid_reconciliation");
+      integer(at, 0, Number.MAX_SAFE_INTEGER);
+      const job = find(key);
+      if (!["uncertain", "queued"].includes(job.state)) fail("reconciliation_not_allowed");
+      if (proof.decision === "confirmed_effect") {
+        job.confirmed = true;
+        job.semantic_acceptance = "accepted";
+        job.state = "confirmed";
+      } else {
+        job.state = job.attempts >= job.policy.max_attempts ? "terminal" : "retry";
+        job.available_at = at;
+      }
+      return snapshot(job);
+    },
+  });
+}

package/templates/.agents/skills/zaip-skill-lead-measurement/scripts/lead-measurement.mjs

@@ -0,0 +1,277 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export class MeasurementContractError extends Error {
+  constructor(code) {
+    super(code);
+    this.name = "MeasurementContractError";
+    this.code = code;
+  }
+}
+export const reject = (code) => {
+  throw new MeasurementContractError(code);
+};
+export const signals = [
+  "analytics_storage",
+  "ad_storage",
+  "ad_user_data",
+  "ad_personalization",
+  "meta_measurement",
+];
+const classifications = ["service", "budget_band", "qualification"];
+const eventNames = ["lead_accepted", "lead_qualified"];
+const enumPattern = /^[a-z][a-z0-9_-]{0,39}$/;
+const versionPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+export function strictObject(value, allowed, required = allowed) {
+  if (
+    !value ||
+    Array.isArray(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  )
+    reject("object_required");
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (
+    Reflect.ownKeys(value).some(
+      (key) =>
+        typeof key !== "string" ||
+        !allowed.includes(key) ||
+        !Object.hasOwn(descriptors[key], "value"),
+    )
+  )
+    reject("unknown_or_unsafe_field");
+  if (required.some((key) => !Object.hasOwn(value, key))) reject("required_field_missing");
+  return value;
+}
+function member(value, accepted, code) {
+  if (!accepted.includes(value)) reject(code);
+}
+function text(value, pattern, code) {
+  if (typeof value !== "string" || !pattern.test(value)) reject(code);
+}
+function integer(value, minimum, maximum) {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum)
+    reject("invalid_integer_policy");
+}
+export function validTimestamp(value) {
+  if (typeof value !== "string") return false;
+  const match =
+    /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(Z|[+-]\d{2}:\d{2})$/.exec(
+      value,
+    );
+  if (!match || !Number.isFinite(Date.parse(value))) return false;
+  const [, year, month, day, hour, minute, second, , zone] = match;
+  const calendar = new Date(0);
+  calendar.setUTCFullYear(Number(year), Number(month), 0);
+  const days = calendar.getUTCDate();
+  return (
+    Number(month) >= 1 &&
+    Number(month) <= 12 &&
+    Number(day) >= 1 &&
+    Number(day) <= days &&
+    Number(hour) <= 23 &&
+    Number(minute) <= 59 &&
+    Number(second) <= 59 &&
+    (zone === "Z" || (Number(zone.slice(1, 3)) <= 23 && Number(zone.slice(4, 6)) <= 59))
+  );
+}
+export function stableJSON(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJSON).join(",")}]`;
+  if (value && typeof value === "object") {
+    strictObject(value, Object.keys(value));
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJSON(value[key])}`)
+      .join(",")}}`;
+  }
+  if (!["string", "number", "boolean"].includes(typeof value) && value !== null)
+    reject("non_json_value");
+  if (typeof value === "number" && !Number.isFinite(value)) reject("non_json_value");
+  return JSON.stringify(value);
+}
+export const fingerprint = (value) => createHash("sha256").update(stableJSON(value)).digest("hex");
+export function freeze(value) {
+  if (value && typeof value === "object") {
+    for (const item of Object.values(value)) freeze(item);
+    Object.freeze(value);
+  }
+  return value;
+}
+export function validateRetryPolicy(policy) {
+  strictObject(policy, ["max_attempts", "base_delay_ms", "max_delay_ms"]);
+  integer(policy.max_attempts, 1, 10);
+  integer(policy.base_delay_ms, 1, 3_600_000);
+  integer(policy.max_delay_ms, policy.base_delay_ms, 3_600_000);
+  return policy;
+}
+export function validateConfig(config) {
+  strictObject(config, [
+    "schema_version",
+    "catalog_version",
+    "mapping_version",
+    "classification_catalog",
+    "events",
+    "google_ads",
+    "required_consent",
+    "retry",
+  ]);
+  if (config.schema_version !== 1) reject("unsupported_config_version");
+  text(config.catalog_version, versionPattern, "invalid_catalog_version");
+  text(config.mapping_version, versionPattern, "invalid_mapping_version");
+  strictObject(config.classification_catalog, classifications);
+  for (const key of classifications) {
+    const values = config.classification_catalog[key];
+    if (
+      !Array.isArray(values) ||
+      values.length < 1 ||
+      values.length > 100 ||
+      new Set(values).size !== values.length
+    )
+      reject("invalid_enum_catalog");
+    for (const value of values) text(value, enumPattern, "invalid_enum_value");
+  }
+  strictObject(config.events, eventNames);
+  for (const event of eventNames) {
+    strictObject(config.events[event], ["ga4", "meta"]);
+    for (const value of Object.values(config.events[event]))
+      text(value, /^[A-Za-z][A-Za-z0-9_]{0,39}$/, "invalid_event_mapping");
+  }
+  if (
+    config.events.lead_accepted.ga4 !== "generate_lead" ||
+    config.events.lead_accepted.meta !== "Lead" ||
+    config.events.lead_qualified.ga4 === "generate_lead" ||
+    config.events.lead_qualified.meta === "Lead"
+  )
+    reject("registration_mapping_conflict");
+  strictObject(config.google_ads, ["primary_source", "sources"]);
+  member(config.google_ads.primary_source, ["ga4_import", "direct"], "invalid_primary_source");
+  strictObject(config.google_ads.sources, ["ga4_import", "direct"]);
+  for (const source of ["ga4_import", "direct"]) {
+    strictObject(config.google_ads.sources[source], ["primary"]);
+    if (config.google_ads.sources[source].primary !== (source === config.google_ads.primary_source))
+      reject("primary_source_conflict");
+  }
+  strictObject(config.required_consent, ["ga4", "google_ads", "meta"]);
+  const minimum = {
+    ga4: ["analytics_storage"],
+    google_ads: ["ad_storage", "ad_user_data"],
+    meta: ["meta_measurement"],
+  };
+  for (const destination of Object.keys(minimum)) {
+    const required = config.required_consent[destination];
+    if (
+      !Array.isArray(required) ||
+      required.length > signals.length ||
+      new Set(required).size !== required.length ||
+      minimum[destination].some((signal) => !required.includes(signal)) ||
+      required.some((signal) => !signals.includes(signal))
+    )
+      reject("invalid_consent_contract");
+  }
+  validateRetryPolicy(config.retry);
+  return freeze(structuredClone(config));
+}
+export function validateEnvelope(event, suppliedConfig) {
+  const config = validateConfig(suppliedConfig);
+  strictObject(
+    event,
+    [
+      "schema_version",
+      "event_id",
+      "event_name",
+      "occurred_at",
+      "acceptance",
+      "classification",
+      "consent",
+    ],
+    ["schema_version", "event_id", "event_name", "occurred_at", "acceptance", "classification"],
+  );
+  if (event.schema_version !== 1) reject("unsupported_event_version");
+  text(event.event_id, /^evt_[A-Za-z0-9_-]{8,96}$/, "invalid_event_id");
+  member(event.event_name, eventNames, "unaccepted_business_event");
+  if (!validTimestamp(event.occurred_at)) reject("invalid_occurrence_timestamp");
+  strictObject(event.acceptance, ["persisted", "receipt_id"]);
+  if (event.acceptance.persisted !== true) reject("backend_acceptance_not_persisted");
+  text(event.acceptance.receipt_id, /^[A-Za-z0-9_-]{8,128}$/, "invalid_internal_receipt");
+  strictObject(event.classification, classifications);
+  for (const key of classifications)
+    member(
+      event.classification[key],
+      config.classification_catalog[key],
+      "classification_not_in_catalog",
+    );
+  const consent = event.consent === undefined ? {} : event.consent;
+  strictObject(consent, signals, []);
+  for (const value of Object.values(consent))
+    member(value, ["granted", "denied", "unknown"], "invalid_consent_value");
+  return freeze({
+    ...structuredClone(event),
+    consent: Object.fromEntries(signals.map((signal) => [signal, consent[signal] ?? "unknown"])),
+  });
+}
+export function projectMeasurement(input, suppliedConfig) {
+  const config = validateConfig(suppliedConfig),
+    event = validateEnvelope(input, config);
+  const permits = (destination) =>
+    config.required_consent[destination].every((signal) => event.consent[signal] === "granted");
+  const projection = (eventName) => ({
+    event_name: eventName,
+    event_id: event.event_id,
+    occurred_at: event.occurred_at,
+    mapping_version: config.mapping_version,
+    parameters: { ...event.classification },
+  });
+  const ga4 = permits("ga4") ? projection(config.events[event.event_name].ga4) : null;
+  const meta = permits("meta") ? projection(config.events[event.event_name].meta) : null;
+  const google_ads =
+    event.event_name === "lead_accepted" &&
+    permits("google_ads") &&
+    (config.google_ads.primary_source !== "ga4_import" || ga4 !== null)
+      ? { ...projection("lead_accepted"), source: config.google_ads.primary_source, primary: true }
+      : null;
+  const data_layer =
+    ga4 || meta || google_ads
+      ? { event: event.event_name, event_id: event.event_id, ...event.classification }
+      : null;
+  return freeze({
+    ga4,
+    google_ads,
+    meta_pixel: meta,
+    meta_capi: meta ? structuredClone(meta) : null,
+    data_layer,
+  });
+}
+
+async function main(argv) {
+  const [action, ...args] = argv;
+  member(action, ["validate", "project"], "unknown_action");
+  const paths = {};
+  for (let i = 0; i < args.length; i += 2) {
+    const flag = args[i];
+    if (
+      !["--event", "--config"].includes(flag) ||
+      Object.hasOwn(paths, flag) ||
+      !args[i + 1] ||
+      args[i + 1].startsWith("--")
+    )
+      reject("invalid_arguments");
+    paths[flag] = args[i + 1];
+  }
+  if (!paths["--event"] || !paths["--config"]) reject("event_and_config_required");
+  const event = JSON.parse(await readFile(paths["--event"], "utf8")),
+    config = JSON.parse(await readFile(paths["--config"], "utf8"));
+  validateEnvelope(event, config);
+  process.stdout.write(
+    `${JSON.stringify(action === "validate" ? { valid: true, model_only: true } : { model_only: true, projections: projectMeasurement(event, config) })}\n`,
+  );
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(
+      `${JSON.stringify({ error: error instanceof MeasurementContractError ? error.code : "input_read_or_parse_failed" })}\n`,
+    );
+    process.exitCode = 1;
+  });
+}