xytara 3.1.16 → 3.2.0

package/lib/commerce_checkout.js

@@ -1,509 +0,0 @@
-"use strict";
-
-const { createRefund, createRemediationTicket } = require("./commerce_cases");
-const { applyRailCredits, buildCreditBalanceSummary, reverseRailCredits } = require("./commerce_economics");
-const { dispatchRuntimeBridgeRequest } = require("./runtime_bridge");
-
-function normalizeString(value, fallback) {
-  const trimmed = typeof value === "string" ? value.trim() : "";
-  return trimmed || fallback || null;
-}
-
-function buildDefaultHostedCheckoutState() {
-  return {
-    checkoutPurchaseIntents: new Map(),
-    checkoutSessions: new Map(),
-    checkoutEvents: new Map(),
-    runtimeBridgeDispatches: new Map(),
-    refunds: new Map()
-  };
-}
-
-function normalizeHostedCheckoutState(state) {
-  const normalized = buildDefaultHostedCheckoutState();
-  if (!state || typeof state !== "object") {
-    return normalized;
-  }
-  for (const [key, value] of Object.entries(state)) {
-    if (typeof value !== "undefined") {
-      normalized[key] = value;
-    }
-  }
-  return normalized;
-}
-
-function ensureObject(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-
-function nowIso() {
-  return new Date().toISOString();
-}
-
-function buildPrice(payload) {
-  const price = ensureObject(payload.price);
-  const amountMinor = Number.isFinite(Number(price.amount_minor))
-    ? Number(price.amount_minor)
-    : Number.isFinite(Number(payload.amount_minor))
-      ? Number(payload.amount_minor)
-      : 0;
-  return {
-    amount_minor: amountMinor,
-    currency: normalizeString(price.currency, normalizeString(payload.currency, "USD"))
-  };
-}
-
-function buildCreditsUnits(payload, price) {
-  if (Number.isFinite(Number(payload.credits_units))) {
-    return Number(payload.credits_units);
-  }
-  if (Number.isFinite(Number(payload.quoted_units))) {
-    return Number(payload.quoted_units);
-  }
-  if (Number.isFinite(Number(payload.quantity))) {
-    return Number(payload.quantity);
-  }
-  return Math.max(1, Math.ceil((price.amount_minor || 0) / 100));
-}
-
-function listHostedCheckoutPurchaseIntents(state, accountId) {
-  const runtimeState = normalizeHostedCheckoutState(state);
-  const intents = Array.from(runtimeState.checkoutPurchaseIntents.values());
-  if (!accountId) return intents;
-  return intents.filter((intent) => intent.account_id === accountId);
-}
-
-function getHostedCheckoutPurchaseIntent(state, purchaseIntentId) {
-  const runtimeState = normalizeHostedCheckoutState(state);
-  return runtimeState.checkoutPurchaseIntents.get(purchaseIntentId) || null;
-}
-
-function createHostedCheckoutPurchaseIntent(state, body) {
-  const runtimeState = normalizeHostedCheckoutState(state);
-  const payload = ensureObject(body);
-  const createdAt = nowIso();
-  const price = buildPrice(payload);
-  const purchaseIntent = {
-    purchase_intent_id: normalizeString(payload.purchase_intent_id, `purchase_${runtimeState.checkoutPurchaseIntents.size + 1}`),
-    account_id: normalizeString(payload.account_id, "acct_demo"),
-    capability_id: normalizeString(payload.capability_id, null),
-    package_id: normalizeString(payload.package_id, null),
-    purchase_mode: normalizeString(payload.purchase_mode, "credits_topup"),
-    entitlement_mode: normalizeString(payload.entitlement_mode, "credits_issue"),
-    quantity: Number.isFinite(Number(payload.quantity)) ? Number(payload.quantity) : 1,
-    price,
-    quoted_units: Number.isFinite(Number(payload.quoted_units)) ? Number(payload.quoted_units) : null,
-    credits_units: buildCreditsUnits(payload, price),
-    task_input: payload.task_input && typeof payload.task_input === "object" && !Array.isArray(payload.task_input)
-      ? payload.task_input
-      : null,
-    metadata: ensureObject(payload.metadata),
-    success_redirect_url: normalizeString(payload.success_redirect_url, null),
-    cancel_redirect_url: normalizeString(payload.cancel_redirect_url, null),
-    idempotency_key: normalizeString(payload.idempotency_key, `checkout_intent_${state.checkoutPurchaseIntents.size + 1}`),
-    checkout_status: "created",
-    customer_status: "created",
-    fulfillment: {
-      credits_issued: false,
-      execution_authorized: false,
-      package_access_granted: false
-    },
-    latest_checkout_session_id: null,
-    latest_checkout_reference: null,
-    latest_event_id: null,
-    created_at_iso: createdAt,
-    updated_at_iso: createdAt
-  };
-  runtimeState.checkoutPurchaseIntents.set(purchaseIntent.purchase_intent_id, purchaseIntent);
-  return purchaseIntent;
-}
-
-function createHostedCheckoutSession(state, purchaseIntentId, body) {
-  const runtimeState = normalizeHostedCheckoutState(state);
-  const payload = ensureObject(body);
-  const purchaseIntent = getHostedCheckoutPurchaseIntent(runtimeState, purchaseIntentId);
-  if (!purchaseIntent) return null;
-
-  const createdAt = nowIso();
-  const expiresAt = Number.isFinite(Number(payload.expires_in_seconds))
-    ? new Date(Date.now() + Number(payload.expires_in_seconds) * 1000).toISOString()
-    : null;
-  const session = {
-    checkout_session_id: normalizeString(payload.checkout_session_id, `checkout_session_${runtimeState.checkoutSessions.size + 1}`),
-    purchase_intent_id: purchaseIntentId,
-    checkout_status: "checkout_pending",
-    checkout_provider: normalizeString(payload.checkout_provider, "hosted_checkout"),
-    checkout_reference: normalizeString(payload.checkout_reference, `checkout_ref_${runtimeState.checkoutSessions.size + 1}`),
-    amount_due_minor: purchaseIntent.price.amount_minor,
-    currency: purchaseIntent.price.currency,
-    expires_at_iso: expiresAt,
-    checkout_url: normalizeString(payload.checkout_url, null),
-    embedded_checkout_payload: ensureObject(payload.embedded_checkout_payload),
-    customer_reference: normalizeString(payload.customer_reference, purchaseIntent.account_id),
-    created_at_iso: createdAt,
-    updated_at_iso: createdAt
-  };
-  runtimeState.checkoutSessions.set(session.checkout_session_id, session);
-  runtimeState.checkoutPurchaseIntents.set(purchaseIntentId, {
-    ...purchaseIntent,
-    checkout_status: "checkout_pending",
-    customer_status: "checkout_pending",
-    latest_checkout_session_id: session.checkout_session_id,
-    latest_checkout_reference: session.checkout_reference,
-    updated_at_iso: createdAt
-  });
-  return session;
-}
-
-function getHostedCheckoutSession(state, checkoutSessionId) {
-  const runtimeState = normalizeHostedCheckoutState(state);
-  return runtimeState.checkoutSessions.get(checkoutSessionId) || null;
-}
-
-function listHostedCheckoutSessions(state, purchaseIntentId) {
-  const runtimeState = normalizeHostedCheckoutState(state);
-  const sessions = Array.from(runtimeState.checkoutSessions.values());
-  if (!purchaseIntentId) return sessions;
-  return sessions.filter((session) => session.purchase_intent_id === purchaseIntentId);
-}
-
-function getHostedCheckoutEvent(state, eventId) {
-  const runtimeState = normalizeHostedCheckoutState(state);
-  return runtimeState.checkoutEvents.get(eventId) || null;
-}
-
-function getRuntimeBridgeDispatchByPurchaseIntent(state, purchaseIntentId) {
-  const runtimeState = normalizeHostedCheckoutState(state);
-  return Array.from(runtimeState.runtimeBridgeDispatches.values()).find((dispatch) =>
-    dispatch && dispatch.purchase_intent_id === purchaseIntentId
-  ) || null;
-}
-
-function createHostedCheckoutRemediationTicket(state, purchaseIntent, event, refund, reasonCode, note) {
-  return createRemediationTicket(state, {
-    transaction_id: null,
-    receipt_id: null,
-    reason_code: reasonCode,
-    action_code: "compensate_or_review",
-    note,
-    actor: { type: "system", role: "hosted_checkout_compensator" },
-    context: {
-      purchase_intent_id: purchaseIntent.purchase_intent_id,
-      refund_id: refund ? refund.refund_id : null,
-      provider_reference: event.provider_reference || null,
-      payment_status: event.payment_status || null,
-      source: "hosted_checkout_compensation"
-    }
-  });
-}
-
-function applyHostedCheckoutCompensation(state, purchaseIntent, event, refund) {
-  const balanceBefore = buildCreditBalanceSummary(state, purchaseIntent.account_id);
-  const currentAvailableUnits = Number(balanceBefore.available_units || 0);
-  const requiredUnits = Number(purchaseIntent.credits_units || 0);
-  const runtimeBridgeDispatch = getRuntimeBridgeDispatchByPurchaseIntent(state, purchaseIntent.purchase_intent_id);
-  const compensation = {
-    compensation_state: "review_required",
-    compensation_path: null,
-    reversal_credit_event_id: null,
-    remediation_ticket_id: null,
-    requires_manual_followup: true,
-    downstream_execution_detected: Boolean(runtimeBridgeDispatch),
-    insufficient_available_units: currentAvailableUnits < requiredUnits
-  };
-
-  if (purchaseIntent.fulfillment && purchaseIntent.fulfillment.credits_issued) {
-    const reversalResult = reverseRailCredits(state, {
-      account_id: purchaseIntent.account_id,
-      purchase_intent_id: purchaseIntent.purchase_intent_id,
-      provider_reference: event.provider_reference,
-      reason: event.payment_status === "chargeback"
-        ? "hosted_checkout_chargeback_compensation"
-        : "hosted_checkout_refund_compensation"
-    });
-    if (reversalResult.ok) {
-      compensation.reversal_credit_event_id = reversalResult.reversal.credit_event_id;
-      compensation.compensation_path = "credit_reversal";
-      compensation.compensation_state = (currentAvailableUnits >= requiredUnits && !runtimeBridgeDispatch)
-        ? "compensated"
-        : "remediation_required";
-      compensation.requires_manual_followup = compensation.compensation_state !== "compensated";
-    } else {
-      compensation.compensation_path = "credit_reversal_failed";
-      compensation.compensation_state = "compensation_failed";
-    }
-  } else if (purchaseIntent.fulfillment && purchaseIntent.fulfillment.execution_authorized) {
-    compensation.compensation_path = "execution_remediation";
-    compensation.compensation_state = "remediation_required";
-  }
-
-  if (compensation.compensation_state !== "compensated") {
-    const note = compensation.downstream_execution_detected
-      ? "Hosted checkout reversal landed after execution dispatch and needs remediation review"
-      : compensation.insufficient_available_units
-        ? "Hosted checkout reversal landed after funded capacity was partially or fully consumed"
-        : "Hosted checkout reversal requires explicit operator review";
-    const ticket = createHostedCheckoutRemediationTicket(
-      state,
-      purchaseIntent,
-      event,
-      refund,
-      event.payment_status === "chargeback" ? "chargeback_compensation_review_required" : "refund_compensation_review_required",
-      note
-    );
-    compensation.remediation_ticket_id = ticket.ticket_id;
-  }
-
-  return compensation;
-}
-
-function listHostedCheckoutRefunds(state, purchaseIntentId) {
-  const refunds = Array.from(state.refunds.values()).filter((refund) => refund && refund.purchase_intent_id);
-  if (!purchaseIntentId) return refunds;
-  return refunds.filter((refund) => refund.purchase_intent_id === purchaseIntentId);
-}
-
-function buildHostedCheckoutOperatorSummary(state, accountId) {
-  const runtimeState = normalizeHostedCheckoutState(state);
-  const purchaseIntents = listHostedCheckoutPurchaseIntents(runtimeState, accountId);
-  const purchaseIntentIds = new Set(purchaseIntents.map((intent) => intent.purchase_intent_id));
-  const refunds = listHostedCheckoutRefunds(runtimeState).filter((refund) => purchaseIntentIds.has(refund.purchase_intent_id));
-  const bridgeDispatches = Array.from(runtimeState.runtimeBridgeDispatches.values()).filter((dispatch) => dispatch && dispatch.account_id === accountId);
-  return {
-    operator_summary_ref: `hosted_checkout.operator.${accountId}`,
-    account_id: accountId,
-    purchase_intent_count: purchaseIntents.length,
-    checkout_pending_count: purchaseIntents.filter((entry) => entry.checkout_status === "checkout_pending").length,
-    paid_intent_count: purchaseIntents.filter((entry) => entry.checkout_status === "paid").length,
-    credits_issued_count: purchaseIntents.filter((entry) => entry.fulfillment && entry.fulfillment.credits_issued).length,
-    execution_dispatched_count: bridgeDispatches.length,
-    refund_review_required_count: purchaseIntents.filter((entry) => entry.customer_status === "refund_review_required" || entry.customer_status === "refund_review_requested").length,
-    auto_compensated_count: purchaseIntents.filter((entry) => entry && entry.compensation && entry.compensation.compensation_state === "compensated").length,
-    compensation_review_required_count: purchaseIntents.filter((entry) => entry && entry.compensation && entry.compensation.compensation_state === "remediation_required").length,
-    compensation_failed_count: purchaseIntents.filter((entry) => entry && entry.compensation && entry.compensation.compensation_state === "compensation_failed").length,
-    refund_case_count: refunds.length,
-    refund_status_counts: refunds.reduce((acc, refund) => {
-      const key = refund && refund.status ? refund.status : "unknown";
-      acc[key] = (acc[key] || 0) + 1;
-      return acc;
-    }, {}),
-    linked_surfaces: {
-      purchase_intents: `/v1/checkout/purchase-intents?account_id=${encodeURIComponent(accountId)}`,
-      runtime_bridge_dispatches: `/v1/runtime-bridge/dispatches?account_id=${encodeURIComponent(accountId)}`
-    }
-  };
-}
-
-function requestHostedCheckoutRefund(state, purchaseIntentId, body) {
-  const purchaseIntent = getHostedCheckoutPurchaseIntent(state, purchaseIntentId);
-  if (!purchaseIntent) return null;
-  const payload = ensureObject(body);
-  const refund = createRefund(state, {
-    purchase_intent_id: purchaseIntentId,
-    transaction_id: normalizeString(payload.transaction_id, null),
-    receipt_id: normalizeString(payload.receipt_id, null),
-    reason_code: normalizeString(payload.reason_code, "refund_review_requested"),
-    note: normalizeString(payload.note, "Hosted checkout refund requested for operator review"),
-    requested_by: normalizeString(payload.requested_by, "checkout_requester"),
-    actor: payload.actor,
-    context: {
-      purchase_intent_id: purchaseIntentId,
-      source: "hosted_checkout",
-      ...(ensureObject(payload.context))
-    }
-  });
-  state.checkoutPurchaseIntents.set(purchaseIntentId, {
-    ...purchaseIntent,
-    customer_status: "refund_review_requested",
-    latest_refund_id: refund.refund_id,
-    updated_at_iso: nowIso()
-  });
-  return refund;
-}
-
-async function normalizeHostedCheckoutEvent(state, body) {
-  const payload = ensureObject(body);
-  const eventId = normalizeString(payload.event_id, null);
-  if (eventId && state.checkoutEvents.has(eventId)) {
-    return state.checkoutEvents.get(eventId);
-  }
-
-  const purchaseIntentId = normalizeString(payload.purchase_intent_id, null);
-  const purchaseIntent = getHostedCheckoutPurchaseIntent(state, purchaseIntentId);
-  if (!purchaseIntent) {
-    return null;
-  }
-
-  const paymentStatus = normalizeString(payload.payment_status, "pending");
-  const timestamp = normalizeString(payload.timestamp, nowIso());
-  const event = {
-    event_id: eventId || `checkout_event_${state.checkoutEvents.size + 1}`,
-    purchase_intent_id: purchaseIntentId,
-    provider: normalizeString(payload.provider, "hosted_checkout"),
-    provider_event_type: normalizeString(payload.provider_event_type, "payment.status"),
-    provider_reference: normalizeString(payload.provider_reference, purchaseIntent.latest_checkout_reference || null),
-    payment_status: paymentStatus,
-    amount_received_minor: Number.isFinite(Number(payload.amount_received_minor))
-      ? Number(payload.amount_received_minor)
-      : purchaseIntent.price.amount_minor,
-    currency: normalizeString(payload.currency, purchaseIntent.price.currency),
-    security_verification: ensureObject(payload.security_verification),
-    timestamp,
-    applied_status: "recorded",
-    credits_event_id: null,
-    created_at_iso: nowIso()
-  };
-
-  const nextIntent = {
-    ...purchaseIntent,
-    latest_event_id: event.event_id,
-    updated_at_iso: event.created_at_iso
-  };
-
-  if (paymentStatus === "paid") {
-    nextIntent.checkout_status = "paid";
-    nextIntent.customer_status = "payment_received";
-    if (purchaseIntent.purchase_mode === "credits_topup" || purchaseIntent.entitlement_mode === "credits_issue") {
-      const creditEvent = applyRailCredits(state, {
-        account_id: purchaseIntent.account_id,
-        credit_event_id: `credit_${purchaseIntent.purchase_intent_id}`,
-        rail_kind: "hosted_checkout",
-        units: purchaseIntent.credits_units,
-        amount_minor: event.amount_received_minor,
-        currency: event.currency,
-        purchase_intent_id: purchaseIntent.purchase_intent_id,
-        provider_reference: event.provider_reference,
-        reason: "hosted_checkout_payment"
-      });
-      event.applied_status = "credits_issued";
-      event.credits_event_id = creditEvent.credit_event_id;
-      nextIntent.customer_status = "credits_issued";
-      nextIntent.fulfillment = {
-        ...nextIntent.fulfillment,
-        credits_issued: true
-      };
-    } else if (purchaseIntent.purchase_mode === "single_task_execution" || purchaseIntent.entitlement_mode === "execution_authorization") {
-      const bridgeDispatch = await dispatchRuntimeBridgeRequest(state, {
-        request_id: `bridge_${purchaseIntent.purchase_intent_id}`,
-        account_id: purchaseIntent.account_id,
-        capability_id: purchaseIntent.capability_id,
-        execution_class: "single_task_execution",
-        input: ensureObject(purchaseIntent.task_input),
-        idempotency_key: purchaseIntent.idempotency_key,
-        callback_url: normalizeString(purchaseIntent.metadata.callback_url, null),
-        defer_completion: purchaseIntent.metadata.defer_completion === true,
-        settlement_mode: normalizeString(purchaseIntent.metadata.settlement_mode, "bsv_teranode"),
-        integration_id: normalizeString(purchaseIntent.metadata.integration_id, null),
-        integration_ids: Array.isArray(purchaseIntent.metadata.integration_ids) ? purchaseIntent.metadata.integration_ids : []
-      }, {
-        verification_mode: "hosted_checkout",
-        wallet_id: event.provider,
-        payment_payload: {
-          purchase_intent_id: purchaseIntent.purchase_intent_id,
-          provider_reference: event.provider_reference
-        },
-        purchase_intent_id: purchaseIntent.purchase_intent_id
-      });
-      event.applied_status = bridgeDispatch.status === 200 ? "execution_dispatched" : "dispatch_failed";
-      event.runtime_bridge_request_id = `bridge_${purchaseIntent.purchase_intent_id}`;
-      nextIntent.customer_status = bridgeDispatch.status === 200 ? "execution_dispatched" : "failed";
-      nextIntent.fulfillment = {
-        ...nextIntent.fulfillment,
-        execution_authorized: bridgeDispatch.status === 200
-      };
-    }
-  } else if (paymentStatus === "failed") {
-    nextIntent.checkout_status = "failed";
-    nextIntent.customer_status = "failed";
-  } else if (paymentStatus === "refunded" || paymentStatus === "chargeback") {
-    nextIntent.checkout_status = paymentStatus;
-    nextIntent.customer_status = "refund_review_required";
-    event.applied_status = "refund_review_required";
-    const existingRefund = listHostedCheckoutRefunds(state, purchaseIntent.purchase_intent_id)[0] || null;
-    const refund = existingRefund || createRefund(state, {
-      purchase_intent_id: purchaseIntent.purchase_intent_id,
-      reason_code: paymentStatus === "chargeback" ? "chargeback_review_required" : "provider_refund_review_required",
-      note: paymentStatus === "chargeback"
-        ? "Chargeback or reversal reported and queued for review"
-        : "Refund reported and queued for review",
-      requested_by: "provider_report",
-      context: {
-        purchase_intent_id: purchaseIntent.purchase_intent_id,
-        source: "hosted_checkout_event",
-        payment_status: paymentStatus,
-        provider_reference: event.provider_reference
-      }
-    });
-    nextIntent.latest_refund_id = refund.refund_id;
-    const compensation = applyHostedCheckoutCompensation(state, purchaseIntent, event, refund);
-    event.compensation = compensation;
-    nextIntent.compensation = compensation;
-    if (compensation.compensation_state === "compensated") {
-      refund.status = "completed";
-      refund.action_code = "auto_compensated";
-      refund.updated_at_iso = nowIso();
-      refund.history = [
-        ...(Array.isArray(refund.history) ? refund.history : []),
-        {
-          at_iso: refund.updated_at_iso,
-          event: "auto_compensated",
-          note: paymentStatus === "chargeback"
-            ? "Chargeback compensation applied automatically"
-            : "Refund compensation applied automatically",
-          reason_code: refund.reason_code,
-          action_code: "auto_compensated",
-          previous_status: "requested",
-          next_status: "completed",
-          actor: { type: "system", role: "hosted_checkout_compensator" },
-          context: {
-            purchase_intent_id: purchaseIntent.purchase_intent_id,
-            provider_reference: event.provider_reference,
-            reversal_credit_event_id: compensation.reversal_credit_event_id
-          }
-        }
-      ].slice(-20);
-      state.refunds.set(refund.refund_id, refund);
-      nextIntent.customer_status = paymentStatus === "chargeback" ? "chargeback_compensated" : "refund_compensated";
-      event.applied_status = "auto_compensated";
-      if (nextIntent.fulfillment) {
-        nextIntent.fulfillment = {
-          ...nextIntent.fulfillment,
-          credits_issued: false
-        };
-      }
-    } else {
-      nextIntent.customer_status = paymentStatus === "chargeback" ? "chargeback_review_required" : "refund_review_required";
-      event.applied_status = compensation.compensation_state === "compensation_failed"
-        ? "compensation_failed"
-        : "refund_review_required";
-    }
-  }
-
-  state.checkoutPurchaseIntents.set(purchaseIntentId, nextIntent);
-  state.checkoutEvents.set(event.event_id, event);
-
-  if (purchaseIntent.latest_checkout_session_id && state.checkoutSessions.has(purchaseIntent.latest_checkout_session_id)) {
-    const session = state.checkoutSessions.get(purchaseIntent.latest_checkout_session_id);
-    state.checkoutSessions.set(purchaseIntent.latest_checkout_session_id, {
-      ...session,
-      checkout_status: nextIntent.checkout_status,
-      updated_at_iso: nowIso()
-    });
-  }
-
-  return event;
-}
-
-module.exports = {
-  createHostedCheckoutPurchaseIntent,
-  createHostedCheckoutSession,
-  getHostedCheckoutEvent,
-  getHostedCheckoutPurchaseIntent,
-  getHostedCheckoutSession,
-  buildHostedCheckoutOperatorSummary,
-  listHostedCheckoutPurchaseIntents,
-  listHostedCheckoutRefunds,
-  listHostedCheckoutSessions,
-  normalizeHostedCheckoutEvent,
-  requestHostedCheckoutRefund
-};