@zaip-ai/cli 6.2.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-meta-conversions/scripts/meta-model.mjs

@@ -0,0 +1,369 @@
+import { createHash } from "node:crypto";
+import { resolveConsent } from "../../zaip-skill-lead-measurement/scripts/consent.mjs";
+import {
+  canonical,
+  classify,
+  clone,
+  eventProjection,
+  fail,
+  fields,
+  freeze,
+  integer,
+} from "../../zaip-skill-lead-measurement/scripts/delivery-v2-contract.mjs";
+
+function validatePolicy(input) {
+  const policy = clone(input);
+  fields(
+    policy,
+    [
+      "owner",
+      "tenant",
+      "environment",
+      "dataset_id",
+      "authorized_dataset_ids",
+      "test_mode",
+      "test_event_code",
+      "matching_fields",
+      "public_url",
+      "inventory",
+    ],
+    [
+      "owner",
+      "tenant",
+      "environment",
+      "dataset_id",
+      "authorized_dataset_ids",
+      "test_mode",
+      "matching_fields",
+      "public_url",
+      "inventory",
+    ],
+  );
+  if (policy.owner !== "server" || typeof policy.test_mode !== "boolean")
+    fail("server_policy_required");
+  for (const key of ["tenant", "dataset_id"])
+    if (typeof policy[key] !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/.test(policy[key]))
+      fail("invalid_target");
+  if (
+    !Array.isArray(policy.authorized_dataset_ids) ||
+    !policy.authorized_dataset_ids.length ||
+    policy.authorized_dataset_ids.length > 20 ||
+    new Set(policy.authorized_dataset_ids).size !== policy.authorized_dataset_ids.length ||
+    policy.authorized_dataset_ids.some(
+      (id) => typeof id !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/.test(id),
+    ) ||
+    !policy.authorized_dataset_ids.includes(policy.dataset_id)
+  )
+    fail("dataset_not_authorized");
+  if (policy.test_mode) {
+    if (
+      policy.environment !== "test" ||
+      typeof policy.test_event_code !== "string" ||
+      !/^[A-Za-z0-9_-]{1,64}$/.test(policy.test_event_code)
+    )
+      fail("test_configuration_incomplete");
+  } else if (policy.environment !== "production" || Object.hasOwn(policy, "test_event_code"))
+    fail("test_code_or_mode_in_production");
+  if (
+    !Array.isArray(policy.matching_fields) ||
+    !policy.matching_fields.length ||
+    policy.matching_fields.some((field) => !["email", "phone"].includes(field)) ||
+    new Set(policy.matching_fields).size !== policy.matching_fields.length
+  )
+    fail("matching_policy_required");
+  let url;
+  try {
+    url = new URL(policy.public_url);
+  } catch {
+    fail("unsafe_public_url");
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname !== "/lead" ||
+    url.href !== policy.public_url
+  )
+    fail("unsafe_public_url");
+  fields(policy.inventory, ["loaders", "datasets", "autoevents", "advanced_matching", "noscript"]);
+  if (
+    !Array.isArray(policy.inventory.loaders) ||
+    policy.inventory.loaders.length !== 1 ||
+    !Array.isArray(policy.inventory.datasets) ||
+    !policy.inventory.datasets.includes(policy.dataset_id) ||
+    policy.inventory.datasets.some((id) => !policy.authorized_dataset_ids.includes(id)) ||
+    [
+      policy.inventory.autoevents,
+      policy.inventory.advanced_matching,
+      policy.inventory.noscript,
+    ].some((flag) => typeof flag !== "boolean")
+  )
+    fail("inventory_unreviewed");
+  return freeze(policy);
+}
+function matching(input, allowed) {
+  const data = clone(input);
+  fields(data, allowed, []);
+  if (!Object.keys(data).length) fail("matching_required");
+  const result = {};
+  for (const [field, raw] of Object.entries(data)) {
+    if (typeof raw !== "string" || raw.length > 254) fail("invalid_matching");
+    let normalized;
+    if (field === "email") {
+      normalized = raw.trim().toLowerCase();
+      if (!/^[\x21-\x7e]+$/.test(normalized) || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalized))
+        fail("invalid_matching");
+    } else {
+      if (!/^\+[0-9 ()-]+$/.test(raw.trim())) fail("explicit_country_code_required");
+      normalized = raw.trim().replace(/[ ()-]/g, "");
+      if (!/^\+[1-9][0-9]{7,14}$/.test(normalized)) fail("invalid_matching");
+      normalized = normalized.slice(1);
+    }
+    result[field === "email" ? "em" : "ph"] = [
+      createHash("sha256").update(normalized, "utf8").digest("hex"),
+    ];
+  }
+  return freeze(result);
+}
+export function createMetaSimulation(options) {
+  fields(options, ["policy", "measurement_config", "readCurrent"]);
+  const policy = validatePolicy(options.policy),
+    config = clone(options.measurement_config),
+    readCurrent = options.readCurrent;
+  if (typeof readCurrent !== "function") fail("current_reader_required");
+  let revision = -1,
+    signature = null,
+    loaded = false;
+  const eventSnapshots = new Map();
+  function eligible() {
+    try {
+      const current = resolveConsent(
+        readCurrent({ tenant: policy.tenant, dataset_id: policy.dataset_id }),
+      );
+      const nextSignature = canonical(current.history);
+      if (
+        current.revision < revision ||
+        (current.revision === revision && nextSignature !== signature)
+      )
+        return false;
+      revision = current.revision;
+      signature = nextSignature;
+      return current.states.meta_measurement === "granted";
+    } catch {
+      return false;
+    }
+  }
+  return Object.freeze({
+    model_only: true,
+    attempt(request, effects) {
+      const input = clone(request);
+      fields(input, ["phase", "event", "client", "private_matching"]);
+      fields(input.client, []);
+      if (!["loader", "base", "page_view", "event", "retry"].includes(input.phase))
+        fail("unknown_phase");
+      fields(effects, ["load", "public", "restricted", "log"]);
+      if (Object.values(effects).some((effect) => typeof effect !== "function"))
+        fail("invalid_effects");
+      if (!eligible()) return { allowed: false, reason: "consent_ineligible" };
+      if (input.phase === "loader" && loaded)
+        return { allowed: true, status: "already_loaded", model_only: true };
+      try {
+        if (input.phase === "loader") {
+          effects.load(freeze({ dataset_id: policy.dataset_id, test_mode: policy.test_mode }));
+          loaded = true;
+        } else if (["base", "page_view"].includes(input.phase)) {
+          effects.public(freeze({ kind: input.phase, dataset_id: policy.dataset_id }));
+        } else {
+          const projected = eventProjection(input.event, config, "meta_capi");
+          const userData = matching(input.private_matching, policy.matching_fields);
+          const publicView = freeze({
+            pixel: {
+              dataset_id: policy.dataset_id,
+              event_name: projected.payload.event_name,
+              eventID: projected.payload.event_id,
+              parameters: clone(projected.payload.parameters),
+            },
+            data_layer: {
+              event: projected.event.event_name,
+              event_id: projected.event.event_id,
+              ...projected.event.classification,
+            },
+            url: policy.public_url,
+          });
+          const payload = {
+            event_name: projected.payload.event_name,
+            event_id: projected.payload.event_id,
+            event_time: Math.floor(Date.parse(projected.payload.occurred_at) / 1000),
+            action_source: "website",
+            user_data: userData,
+            custom_data: clone(projected.payload.parameters),
+          };
+          if (policy.test_mode) payload.test_event_code = policy.test_event_code;
+          const restricted = freeze({
+            target: {
+              tenant: policy.tenant,
+              dataset_id: policy.dataset_id,
+              environment: policy.environment,
+              test_mode: policy.test_mode,
+            },
+            payload,
+          });
+          const snapshot = canonical({ publicView, restricted });
+          if (
+            eventSnapshots.has(payload.event_id) &&
+            eventSnapshots.get(payload.event_id) !== snapshot
+          )
+            fail("event_identity_conflict");
+          eventSnapshots.set(payload.event_id, snapshot);
+          effects.public(publicView);
+          effects.restricted(restricted);
+        }
+        effects.log(
+          freeze({
+            code: "modeled",
+            dataset_id: policy.dataset_id,
+            phase: input.phase,
+            test_mode: policy.test_mode,
+          }),
+        );
+      } catch {
+        return { allowed: false, reason: "model_or_effect_incomplete" };
+      }
+      return { allowed: true, model_only: true };
+    },
+  });
+}
+export function pairInvariant(publicPixel, restricted) {
+  const pixel = clone(publicPixel),
+    server = clone(restricted);
+  fields(pixel, ["dataset_id", "event_name", "eventID", "parameters"]);
+  fields(server, ["target", "payload"]);
+  if (
+    pixel.dataset_id !== server.target.dataset_id ||
+    pixel.event_name !== server.payload.event_name ||
+    pixel.eventID !== server.payload.event_id
+  )
+    fail("pair_identity_mismatch");
+  return { same_fact: true, deduplication_observed: false, dedupe_window_verified: false };
+}
+function hasTestCode(value) {
+  if (!value || typeof value !== "object") return false;
+  return Object.entries(value).some(
+    ([key, nested]) => key === "test_event_code" || hasTestCode(nested),
+  );
+}
+export function productionCutover(input) {
+  const state = clone(input);
+  fields(state, [
+    "approved_target",
+    "effective_config",
+    "payloads",
+    "jobs",
+    "activation_ms",
+    "prior_test_event_ids",
+    "existing_event_ids",
+  ]);
+  fields(state.approved_target, ["tenant", "dataset_id"]);
+  const policy = validatePolicy(state.effective_config);
+  if (
+    policy.tenant !== state.approved_target.tenant ||
+    policy.dataset_id !== state.approved_target.dataset_id
+  )
+    fail("cutover_target_divergence");
+  integer(state.activation_ms, 0, Number.MAX_SAFE_INTEGER);
+  if (policy.test_mode !== false || policy.environment !== "production" || hasTestCode(state))
+    fail("test_material_remains");
+  if (
+    !Array.isArray(state.payloads) ||
+    !Array.isArray(state.jobs) ||
+    !Array.isArray(state.prior_test_event_ids) ||
+    !Array.isArray(state.existing_event_ids)
+  )
+    fail("cutover_inventory_required");
+  for (const ids of [state.prior_test_event_ids, state.existing_event_ids]) {
+    if (
+      new Set(ids).size !== ids.length ||
+      ids.some((id) => typeof id !== "string" || !/^evt_[A-Za-z0-9_-]{8,96}$/.test(id))
+    )
+      fail("invalid_event_inventory");
+  }
+  const freshFact = (payload) => {
+    fields(payload, [
+      "event_name",
+      "event_id",
+      "event_time",
+      "action_source",
+      "user_data",
+      "custom_data",
+    ]);
+    integer(payload.event_time, 0, Math.floor(Number.MAX_SAFE_INTEGER / 1000));
+    return (
+      typeof payload.event_id === "string" &&
+      /^evt_[A-Za-z0-9_-]{8,96}$/.test(payload.event_id) &&
+      payload.event_time * 1000 >= state.activation_ms &&
+      !state.prior_test_event_ids.includes(payload.event_id) &&
+      !state.existing_event_ids.includes(payload.event_id)
+    );
+  };
+  for (const item of state.payloads) {
+    fields(item, ["target", "payload"]);
+    fields(item.target, ["tenant", "dataset_id", "environment", "test_mode"]);
+    if (
+      item.target.tenant !== policy.tenant ||
+      item.target.dataset_id !== policy.dataset_id ||
+      item.target.environment !== "production" ||
+      item.target.test_mode !== false ||
+      !freshFact(item.payload)
+    )
+      fail("payload_target_or_test_replay");
+  }
+  for (const job of state.jobs) {
+    fields(job, [
+      "origin_mode",
+      "test_mode",
+      "dataset_id",
+      "event_id",
+      "created_ms",
+      "state",
+      "payload",
+    ]);
+    integer(job.created_ms, 0, Number.MAX_SAFE_INTEGER);
+    if (
+      job.origin_mode !== "production" ||
+      job.test_mode !== false ||
+      job.dataset_id !== policy.dataset_id ||
+      job.created_ms < state.activation_ms ||
+      job.state !== "new" ||
+      !freshFact(job.payload) ||
+      job.payload.event_id !== job.event_id
+    )
+      fail("job_test_replay_or_backfill");
+  }
+  return {
+    ready: true,
+    model_only: true,
+    test_jobs_promoted: false,
+    backfill: false,
+    deployment_verified: false,
+  };
+}
+export function semanticReceipt(response) {
+  const outcome = classify("meta_capi", response);
+  return {
+    state: outcome.state,
+    semantic_acceptance: outcome.semantic,
+    transport: outcome.transport,
+    ingestion_confirmed: false,
+    deduplication_observed: false,
+    attributed: false,
+  };
+}
+export function matchesConversion(parameters, rule) {
+  const values = clone(parameters),
+    predicate = clone(rule);
+  fields(values, ["service", "budget_band", "qualification"]);
+  fields(predicate, ["service", "qualification"]);
+  return values.service === predicate.service && values.qualification === predicate.qualification;
+}