xytara 2.5.0 → 2.6.0

package/lib/commerce_client.js

@@ -1499,6 +1499,26 @@ function summarizeDeliveryPayload(payload) {
     status: delivery.status || null,
     attempt_count: Number(delivery.attempt_count || 0),
     last_attempt_at_iso: delivery.last_attempt_at_iso || null,
+    callback_delivery_status: delivery.callback_delivery && delivery.callback_delivery.status
+      ? delivery.callback_delivery.status
+      : null,
+    callback_delivery_attempt_count: Number(
+      delivery.callback_delivery && delivery.callback_delivery.attempt_count
+        ? delivery.callback_delivery.attempt_count
+        : 0
+    ),
+    callback_next_attempt_at_iso: delivery.callback_delivery && delivery.callback_delivery.next_attempt_at_iso
+      ? delivery.callback_delivery.next_attempt_at_iso
+      : null,
+    callback_delivered_at_iso: delivery.callback_delivery && delivery.callback_delivery.delivered_at_iso
+      ? delivery.callback_delivery.delivered_at_iso
+      : null,
+    callback_failed_at_iso: delivery.callback_delivery && delivery.callback_delivery.failed_at_iso
+      ? delivery.callback_delivery.failed_at_iso
+      : null,
+    callback_last_error: delivery.callback_delivery && delivery.callback_delivery.last_error
+      ? delivery.callback_delivery.last_error
+      : null,
     created_at_iso: delivery.created_at_iso || null,
     delivered_at_iso: delivery.delivered_at_iso || null,
     history_count: Array.isArray(delivery.history) ? delivery.history.length : 0

package/lib/commerce_economics.js

@@ -226,6 +226,8 @@ function applyRailCredits(state, body) {
     currency: normalizeString(payload.currency, null),
     purchase_intent_id: normalizeString(payload.purchase_intent_id, null),
     provider_reference: normalizeString(payload.provider_reference, null),
+    normalized_event_kind: "mint",
+    reverses_credit_event_id: null,
     created_at_iso: nowIso(),
     applied_status: "recorded"
   };
@@ -233,6 +235,92 @@ function applyRailCredits(state, body) {
   return event;
 }
 
+function reverseRailCredits(state, body) {
+  const payload = ensureObject(body);
+  const accountId = normalizeString(payload.account_id, "acct_demo");
+  const originalCreditEventId = normalizeString(payload.credit_event_id, null);
+  const purchaseIntentId = normalizeString(payload.purchase_intent_id, null);
+  const providerReference = normalizeString(payload.provider_reference, null);
+  const credits = ensureArray(state.economicsRailCredits);
+  const original = credits.find((entry) => {
+    if (!entry || entry.account_id !== accountId || entry.normalized_event_kind === "reverse") return false;
+    if (originalCreditEventId && entry.credit_event_id === originalCreditEventId) return true;
+    if (purchaseIntentId && entry.purchase_intent_id === purchaseIntentId) return true;
+    if (providerReference && entry.provider_reference === providerReference) return true;
+    return false;
+  });
+
+  if (!original) {
+    return {
+      ok: false,
+      reason: "credit_event_not_found",
+      account_id: accountId,
+      credit_event_id: originalCreditEventId,
+      purchase_intent_id: purchaseIntentId
+    };
+  }
+
+  const existingReversal = credits.find((entry) =>
+    entry
+    && entry.account_id === accountId
+    && entry.normalized_event_kind === "reverse"
+    && entry.reverses_credit_event_id === original.credit_event_id
+  );
+  if (existingReversal) {
+    return {
+      ok: true,
+      reversal: existingReversal,
+      original,
+      already_reversed: true
+    };
+  }
+
+  const reversalUnits = Number.isFinite(Number(payload.units))
+    ? Math.max(0, Number(payload.units))
+    : Math.max(0, Number(original.units || 0));
+  const reversal = {
+    credit_event_id: normalizeString(payload.reversal_credit_event_id, `credit_reverse_${state.economicsRailCredits.length + 1}`),
+    account_id: accountId,
+    rail_kind: normalizeString(payload.rail_kind, original.rail_kind || "payment_credit"),
+    units: reversalUnits,
+    preview_status: "admissible",
+    normalized_event_kind: "reverse",
+    reverses_credit_event_id: original.credit_event_id,
+    amount_minor: Number.isFinite(Number(payload.amount_minor))
+      ? Number(payload.amount_minor)
+      : Number.isFinite(Number(original.amount_minor))
+        ? Number(original.amount_minor)
+        : null,
+    currency: normalizeString(payload.currency, original.currency || null),
+    purchase_intent_id: purchaseIntentId || original.purchase_intent_id || null,
+    provider_reference: providerReference || original.provider_reference || null,
+    reason: normalizeString(payload.reason, "hosted_checkout_refund_compensation"),
+    created_at_iso: nowIso(),
+    applied_status: "recorded"
+  };
+  state.economicsRailCredits = [reversal, ...credits].slice(0, 200);
+  return {
+    ok: true,
+    reversal,
+    original,
+    already_reversed: false
+  };
+}
+
+function summarizeRailCreditLifecycle(credits) {
+  const allCredits = Array.isArray(credits) ? credits : [];
+  return {
+    mint_count: allCredits.filter((entry) => entry && entry.normalized_event_kind !== "reverse").length,
+    reverse_count: allCredits.filter((entry) => entry && entry.normalized_event_kind === "reverse").length,
+    minted_units: allCredits
+      .filter((entry) => entry && entry.normalized_event_kind !== "reverse")
+      .reduce((sum, entry) => sum + Number(entry.units || 0), 0),
+    reversed_units: allCredits
+      .filter((entry) => entry && entry.normalized_event_kind === "reverse")
+      .reduce((sum, entry) => sum + Number(entry.units || 0), 0)
+  };
+}
+
 function listEntitlementsForAccount(state, accountId) {
   return Array.from(state.economicsEntitlements.values()).filter((item) => item && item.account_id === accountId);
 }
@@ -493,9 +581,11 @@ function buildCreditBalanceSummary(state, accountId) {
   const credits = listRailCreditsForAccount(state, accountId);
   const allocations = listAllocationEventsForAccount(state, accountId);
   const spends = listCreditSpendsForAccount(state, accountId);
+  const railCreditLifecycle = summarizeRailCreditLifecycle(credits);
   const issuedUnits = allocations.filter((entry) => entry.direction === "mint").reduce((sum, entry) => sum + (entry.units || 0), 0)
-    + credits.reduce((sum, entry) => sum + (entry.units || 0), 0);
-  const reversedUnits = allocations.filter((entry) => entry.direction === "reverse").reduce((sum, entry) => sum + (entry.units || 0), 0);
+    + railCreditLifecycle.minted_units;
+  const reversedUnits = allocations.filter((entry) => entry.direction === "reverse").reduce((sum, entry) => sum + (entry.units || 0), 0)
+    + railCreditLifecycle.reversed_units;
   const consumedUnits = spends.reduce((sum, entry) => sum + (entry.units || 0), 0);
   return {
     account_id: accountId,
@@ -574,10 +664,11 @@ function buildWalletLifecycleSummary(state, accountId) {
   const railCredits = listRailCreditsForAccount(state, accountId);
   const creditSpends = listCreditSpendsForAccount(state, accountId);
   const usageMeters = listUsageMetersForAccount(state, accountId);
+  const railCreditLifecycle = summarizeRailCreditLifecycle(railCredits);
   const mintedUnits = allocations
     .filter((entry) => entry && entry.direction === "mint")
     .reduce((sum, entry) => sum + Number(entry.units || 0), 0)
-    + railCredits.reduce((sum, entry) => sum + Number(entry.units || 0), 0);
+    + railCreditLifecycle.minted_units;
   const reservedUnits = allocations
     .filter((entry) => entry && entry.direction === "reserve")
     .reduce((sum, entry) => sum + Number(entry.units || 0), 0);
@@ -596,7 +687,8 @@ function buildWalletLifecycleSummary(state, accountId) {
     .reduce((sum, entry) => sum + Number(entry.units || 0), 0);
   const reversedUnits = allocations
     .filter((entry) => entry && entry.direction === "reverse")
-    .reduce((sum, entry) => sum + Number(entry.units || 0), 0);
+    .reduce((sum, entry) => sum + Number(entry.units || 0), 0)
+    + railCreditLifecycle.reversed_units;
   const committedUnits = explicitCommittedUnits + spendCommittedUnits;
   const openReservedUnits = Math.max(0, reservedUnits - releasedUnits);
   const correctionState = reversedUnits > 0 ? "corrective_activity_present" : "none";
@@ -635,7 +727,7 @@ function buildWalletLifecycleSummary(state, accountId) {
     record_interpretation: {
       mint_sources: {
         allocation_mint_count: allocations.filter((entry) => entry && entry.direction === "mint").length,
-        rail_credit_count: railCredits.length
+        rail_credit_count: railCreditLifecycle.mint_count
       },
       reserve_sources: {
         allocation_reserve_count: allocations.filter((entry) => entry && entry.direction === "reserve").length
@@ -649,7 +741,8 @@ function buildWalletLifecycleSummary(state, accountId) {
         allocation_release_count: allocations.filter((entry) => entry && entry.direction === "release").length
       },
       reverse_sources: {
-        allocation_reverse_count: allocations.filter((entry) => entry && entry.direction === "reverse").length
+        allocation_reverse_count: allocations.filter((entry) => entry && entry.direction === "reverse").length,
+        rail_credit_reverse_count: railCreditLifecycle.reverse_count
       }
     },
     linked_surfaces: {
@@ -1388,9 +1481,11 @@ function buildTreasurySummary(state, accountId) {
   const spends = listCreditSpendsForAccount(state, accountId);
   const paymentLedger = listPaymentLedgerForAccount(state, accountId);
   const budgets = listMapValuesByAccount(state.economicsBudgets, accountId);
+  const railCreditLifecycle = summarizeRailCreditLifecycle(credits);
   const mintedUnits = allocations.filter((entry) => entry.direction === "mint").reduce((sum, entry) => sum + (entry.units || 0), 0)
-    + credits.reduce((sum, entry) => sum + (entry.units || 0), 0);
-  const reversedUnits = allocations.filter((entry) => entry.direction === "reverse").reduce((sum, entry) => sum + (entry.units || 0), 0);
+    + railCreditLifecycle.minted_units;
+  const reversedUnits = allocations.filter((entry) => entry.direction === "reverse").reduce((sum, entry) => sum + (entry.units || 0), 0)
+    + railCreditLifecycle.reversed_units;
   const consumedUnits = spends.reduce((sum, entry) => sum + (entry.units || 0), 0);
   const settledMinor = paymentLedger.reduce((sum, entry) => sum + (entry.amount_minor || 0), 0);
   const committedUnits = listTransactionsForAccount(state, accountId).length;
@@ -3596,6 +3691,7 @@ function buildNetworkParticipationPackage(state, accountId) {
 
 function buildRailSummary(state, accountId) {
   const credits = listRailCreditsForAccount(state, accountId);
+  const railCreditLifecycle = summarizeRailCreditLifecycle(credits);
   const paymentLedger = listPaymentLedgerForAccount(state, accountId);
   const spends = listCreditSpendsForAccount(state, accountId);
   const entitlements = listEntitlementsForAccount(state, accountId);
@@ -3603,7 +3699,10 @@ function buildRailSummary(state, accountId) {
   return {
     account_id: accountId,
     credit_event_count: credits.length,
-    credit_units_total: credits.reduce((sum, entry) => sum + (entry.units || 0), 0),
+    credit_mint_count: railCreditLifecycle.mint_count,
+    credit_reverse_count: railCreditLifecycle.reverse_count,
+    credit_units_total: railCreditLifecycle.minted_units,
+    reversed_credit_units_total: railCreditLifecycle.reversed_units,
     credit_spend_count: spends.length,
     entitlement_count: entitlements.length,
     low_balance_entitlement_count: replenishment.low_balance_count,
@@ -3811,6 +3910,7 @@ module.exports = {
   recordAllocationEvent,
   previewRailCredits,
   applyRailCredits,
+  reverseRailCredits,
   buildCreditBalanceSummary,
   buildWalletSummary,
   buildWalletLifecycleSummary,

package/lib/commerce_runtime.js

@@ -65,6 +65,24 @@ function buildDeliveryEvent(event, delivery, atIso, extra) {
   };
 }
 
+function buildCallbackDeliveryState(callbackUrl, deliveredAtIso, options = {}) {
+  if (!callbackUrl) return null;
+  const opts = options || {};
+  const initialStatus = opts.initial_status || (deliveredAtIso ? "queued" : "pending_execution");
+  return {
+    status: initialStatus,
+    attempt_count: 0,
+    max_attempts: null,
+    last_attempt_at_iso: null,
+    next_attempt_at_iso: deliveredAtIso || null,
+    delivered_at_iso: null,
+    failed_at_iso: null,
+    last_error: null,
+    last_response_status: null,
+    signature_mode: "hmac_sha256"
+  };
+}
+
 function completePendingExecution(state, transactionId) {
   if (!transactionId || !state.pendingExecutions.has(transactionId) || !state.transactions.has(transactionId)) {
     return state.transactions.get(transactionId) || null;
@@ -142,7 +160,16 @@ function completePendingExecution(state, transactionId) {
         buildDeliveryEvent("delivered", { ...delivery, status: "delivered", proof_ref: next.receipt.proof_ref }, completedAtIso, {
           attempt_number: (delivery.attempt_count || 0) + 1
         })
-      ]
+      ],
+      callback_delivery: delivery.callback_url
+        ? {
+            ...(delivery.callback_delivery || buildCallbackDeliveryState(delivery.callback_url, completedAtIso)),
+            status: "queued",
+            next_attempt_at_iso: completedAtIso,
+            last_error: null,
+            failed_at_iso: null
+          }
+        : null
     };
     state.deliveries.set(pending.deliveryId, nextDelivery);
   }
@@ -161,7 +188,8 @@ function createCommandResult(state, payload, quote, options) {
   const deferredCompletion = payload && payload.defer_completion === true;
   const { transaction, receipt, command } = createCommandArtifacts(payload, quote, {
     deferredCompletion,
-    paymentVerification: opts.paymentVerification || null
+    paymentVerification: opts.paymentVerification || null,
+    externalExecution: opts.externalExecution || null
   });
   const result = { transaction, receipt, command };
   state.transactions.set(transaction.transaction_id, result);
@@ -230,6 +258,13 @@ function createCommandResult(state, payload, quote, options) {
     delivered_at_iso: deferredCompletion ? null : receipt.created_at_iso,
     attempt_count: deferredCompletion ? 0 : 1,
     last_attempt_at_iso: deferredCompletion ? null : receipt.created_at_iso,
+    callback_delivery: buildCallbackDeliveryState(
+      transaction.callback_url,
+      deferredCompletion ? null : receipt.created_at_iso,
+      {
+        initial_status: deferredCompletion ? "pending_execution" : "queued"
+      }
+    ),
     history: [
       buildDeliveryEvent("created", {
         callback_url: transaction.callback_url,
@@ -263,6 +298,7 @@ function createCommandResult(state, payload, quote, options) {
 }
 
 module.exports = {
+  buildCallbackDeliveryState,
   completePendingExecution,
   createCommandResult,
   createDispute,

package/lib/commerce_shell.js

@@ -167,8 +167,10 @@ function buildOperatorShellSummary(input) {
       coordination_zone_count: Number(coordinationAdminView.zone_count || coordinationOperatorView.zone_count || 0),
       hosted_checkout_purchase_intent_count: Number(hostedCheckoutOperatorSummary.purchase_intent_count || 0),
       hosted_checkout_refund_review_required_count: Number(hostedCheckoutOperatorSummary.refund_review_required_count || 0),
-      hosted_checkout_execution_dispatched_count: Number(hostedCheckoutOperatorSummary.execution_dispatched_count || 0)
-      ,
+      hosted_checkout_execution_dispatched_count: Number(hostedCheckoutOperatorSummary.execution_dispatched_count || 0),
+      hosted_checkout_auto_compensated_count: Number(hostedCheckoutOperatorSummary.auto_compensated_count || 0),
+      hosted_checkout_compensation_review_required_count: Number(hostedCheckoutOperatorSummary.compensation_review_required_count || 0),
+      hosted_checkout_compensation_failed_count: Number(hostedCheckoutOperatorSummary.compensation_failed_count || 0),
       low_balance_entitlement_count: Number(entitlementReplenishmentSummary.low_balance_count || 0),
       depleted_entitlement_count: Number(entitlementReplenishmentSummary.depleted_count || 0),
       runtime_snapshot_enabled: runtimeDurability.enabled === true,

package/lib/external_execution_runtime.js

@@ -0,0 +1,132 @@
+"use strict";
+
+const { buildFetchOptionsForPurpose } = require("./network_transport");
+
+function normalizeString(value, fallback = "") {
+  const raw = typeof value === "string" ? value.trim() : "";
+  return raw || fallback;
+}
+
+function ensureObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function loadExecutionTargetRegistry() {
+  const raw = String(process.env.XYTARA_EXECUTION_TARGETS_JSON || "").trim();
+  if (!raw) return [];
+  let parsed = [];
+  try {
+    parsed = JSON.parse(raw);
+  } catch (_) {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  return parsed
+    .map((entry, index) => {
+      const item = ensureObject(entry);
+      const targetId = normalizeString(item.target_id, `execution_target_${index + 1}`);
+      const endpointUrl = normalizeString(item.endpoint_url);
+      if (!endpointUrl) return null;
+      return {
+        target_id: targetId,
+        endpoint_url: endpointUrl,
+        task_ref: normalizeString(item.task_ref) || null,
+        tool_name: normalizeString(item.tool_name) || null,
+        integration_id: normalizeString(item.integration_id) || null,
+        provider: normalizeString(item.provider, "external_execution"),
+        auth_token: normalizeString(item.auth_token) || null,
+        timeout_ms: Math.max(500, Number(item.timeout_ms || 10000) || 10000),
+        enabled: item.enabled !== false
+      };
+    })
+    .filter(Boolean);
+}
+
+function resolveExecutionTarget(payload, quote) {
+  const registry = loadExecutionTargetRegistry();
+  if (registry.length < 1) return null;
+  const body = ensureObject(payload && payload.body);
+  const taskRefs = Array.isArray(payload && payload.tasks) && payload.tasks.length > 0
+    ? payload.tasks.map((task) => normalizeString(task && task.task_ref)).filter(Boolean)
+    : [normalizeString(payload && payload.task_ref)].filter(Boolean);
+  const toolName = normalizeString(body.tool_name) || null;
+  const integrationIds = new Set(
+    []
+      .concat(normalizeString(payload && payload.integration_id) ? [normalizeString(payload && payload.integration_id)] : [])
+      .concat(Array.isArray(payload && payload.integration_ids) ? payload.integration_ids.map((value) => normalizeString(value)).filter(Boolean) : [])
+      .concat(Array.isArray(quote && quote.integration_ids) ? quote.integration_ids.map((value) => normalizeString(value)).filter(Boolean) : [])
+  );
+
+  return registry.find((target) => {
+    if (!target.enabled) return false;
+    if (target.task_ref && !taskRefs.includes(target.task_ref)) return false;
+    if (target.tool_name && target.tool_name !== toolName) return false;
+    if (target.integration_id && !integrationIds.has(target.integration_id)) return false;
+    return true;
+  }) || null;
+}
+
+async function executeExternalTarget(target, payload, quote, authorizationContext) {
+  if (!target) return null;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), target.timeout_ms);
+  const body = JSON.stringify({
+    command: payload && payload.command ? payload.command : "command.execute",
+    task_ref: payload && payload.task_ref ? payload.task_ref : null,
+    tasks: Array.isArray(payload && payload.tasks) ? payload.tasks : [],
+    body: ensureObject(payload && payload.body),
+    account_id: payload && payload.account_id ? payload.account_id : null,
+    quote,
+    authorization_context: authorizationContext || null
+  });
+  try {
+    const response = await fetch(target.endpoint_url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...(target.auth_token ? { authorization: `Bearer ${target.auth_token}` } : {})
+      },
+      body,
+      signal: controller.signal,
+      ...buildFetchOptionsForPurpose("external_execution")
+    });
+    const text = await response.text();
+    let parsed = null;
+    try {
+      parsed = text ? JSON.parse(text) : null;
+    } catch (_) {
+      parsed = null;
+    }
+    if (!response.ok) {
+      return {
+        ok: false,
+        status: 502,
+        reason: "external_execution_target_rejected",
+        details: parsed || text || null,
+        provider: target.provider
+      };
+    }
+    return {
+      ok: true,
+      provider: target.provider,
+      target_id: target.target_id,
+      target_response: parsed || null
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      status: error && error.name === "AbortError" ? 504 : 502,
+      reason: error && error.name === "AbortError" ? "external_execution_timeout" : "external_execution_failed",
+      details: error && error.message ? error.message : "external execution failed",
+      provider: target.provider
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+module.exports = {
+  executeExternalTarget,
+  loadExecutionTargetRegistry,
+  resolveExecutionTarget
+};