xytara 1.15.0 → 1.17.0

package/README.md

@@ -163,6 +163,24 @@ The current `1.15.0` line starts turning that same contract path into a clearer
 
 This is intended to make the transaction-side continuation path easier to hand across a stable adapter-ready bridge instead of treating bridge preparation as an implicit follow-on concern.
 
+The current `1.16.0` line starts turning that bridge into a clearer stable public handoff contract:
+
+- prepared-artifact handoff summaries on top of the bridge path
+- direct handoff template surfaces for proof-side handoff continuity review
+- compact handoff bundles for direct transaction-side handoff reuse
+- compact handoff-carry surfaces for direct transaction-side handoff reuse
+
+This is intended to make the transaction-side continuation path easier to treat as a stable handoff contract instead of only a well-described bridge.
+
+The current `1.17.0` line starts turning that stable handoff contract into a clearer adapter-consumable handoff surface:
+
+- adapter-consumable handoff-surface summaries on top of prepared handoff artifacts
+- direct handoff-surface template routes for proof-side intake review
+- compact handoff-surface bundles for direct adapter-facing reuse
+- clearer adapter-facing handoff-surface ids and stable consumable carry
+
+This is intended to make the transaction-side continuation path easier to consume directly as a stable adapter-facing handoff surface instead of only a well-described handoff contract.
+
 ## Package Surface
 
 The SDK is broad, but it stays organized into a few repeatable families instead of one-off surfaces.

package/index.js

@@ -40,7 +40,7 @@ const {
 } = require("./integrations/registry");
 
 const COMMERCE_SDK_NAME = "xytara";
-const COMMERCE_SDK_VERSION = "1.15.0";
+const COMMERCE_SDK_VERSION = "1.17.0";
 const COMMERCE_API_VERSION = "v1";
 
 function createClient(options) {

package/lib/commerce_client.js

@@ -4520,6 +4520,118 @@ class CommerceClient {
     });
   }
 
+  async prepareInteractionResultPackageHandoffSummary(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/handoff-summary", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.handoff.summary",
+      continuation_ref: String(continuationRef || "").trim(),
+      body: body || {},
+      callback_url: opts.callbackUrl || null,
+      settlement_mode: opts.settlementMode || null,
+      payment_protocol: opts.paymentProtocol || null,
+      protocol: opts.protocol || null,
+      integration_id: opts.integrationId || null,
+      integration_ids: Array.isArray(opts.integrationIds) ? opts.integrationIds : [],
+      integration_context: opts.integrationContext || null
+    });
+  }
+
+  async prepareInteractionResultPackageHandoffTemplate(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/handoff-template", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.handoff.template",
+      continuation_ref: String(continuationRef || "").trim(),
+      body: body || {},
+      callback_url: opts.callbackUrl || null,
+      settlement_mode: opts.settlementMode || null,
+      payment_protocol: opts.paymentProtocol || null,
+      protocol: opts.protocol || null,
+      integration_id: opts.integrationId || null,
+      integration_ids: Array.isArray(opts.integrationIds) ? opts.integrationIds : [],
+      integration_context: opts.integrationContext || null
+    });
+  }
+
+  async prepareInteractionResultPackageHandoffBundle(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/handoff-bundle", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.handoff.bundle",
+      continuation_ref: String(continuationRef || "").trim(),
+      body: body || {},
+      callback_url: opts.callbackUrl || null,
+      settlement_mode: opts.settlementMode || null,
+      payment_protocol: opts.paymentProtocol || null,
+      protocol: opts.protocol || null,
+      integration_id: opts.integrationId || null,
+      integration_ids: Array.isArray(opts.integrationIds) ? opts.integrationIds : [],
+      integration_context: opts.integrationContext || null
+    });
+  }
+
+  async prepareInteractionResultPackageHandoffCarry(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/handoff-carry", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.handoff.carry",
+      continuation_ref: String(continuationRef || "").trim(),
+      body: body || {},
+      callback_url: opts.callbackUrl || null,
+      settlement_mode: opts.settlementMode || null,
+      payment_protocol: opts.paymentProtocol || null,
+      protocol: opts.protocol || null,
+      integration_id: opts.integrationId || null,
+      integration_ids: Array.isArray(opts.integrationIds) ? opts.integrationIds : [],
+      integration_context: opts.integrationContext || null
+    });
+  }
+
+  async prepareInteractionResultPackageHandoffSurfaceSummary(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/handoff-surface-summary", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.handoff.surface.summary",
+      continuation_ref: String(continuationRef || "").trim(),
+      body: body || {},
+      callback_url: opts.callbackUrl || null,
+      settlement_mode: opts.settlementMode || null,
+      payment_protocol: opts.paymentProtocol || null,
+      protocol: opts.protocol || null,
+      integration_id: opts.integrationId || null,
+      integration_ids: Array.isArray(opts.integrationIds) ? opts.integrationIds : [],
+      integration_context: opts.integrationContext || null
+    });
+  }
+
+  async prepareInteractionResultPackageHandoffSurfaceTemplate(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/handoff-surface-template", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.handoff.surface.template",
+      continuation_ref: String(continuationRef || "").trim(),
+      body: body || {},
+      callback_url: opts.callbackUrl || null,
+      settlement_mode: opts.settlementMode || null,
+      payment_protocol: opts.paymentProtocol || null,
+      protocol: opts.protocol || null,
+      integration_id: opts.integrationId || null,
+      integration_ids: Array.isArray(opts.integrationIds) ? opts.integrationIds : [],
+      integration_context: opts.integrationContext || null
+    });
+  }
+
+  async prepareInteractionResultPackageHandoffSurfaceBundle(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare/handoff-surface-bundle", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.handoff.surface.bundle",
+      continuation_ref: String(continuationRef || "").trim(),
+      body: body || {},
+      callback_url: opts.callbackUrl || null,
+      settlement_mode: opts.settlementMode || null,
+      payment_protocol: opts.paymentProtocol || null,
+      protocol: opts.protocol || null,
+      integration_id: opts.integrationId || null,
+      integration_ids: Array.isArray(opts.integrationIds) ? opts.integrationIds : [],
+      integration_context: opts.integrationContext || null
+    });
+  }
+
   async runNamedTaskRoute(path, payload) {
     if (!this.apiKey || !this.walletId || !this.walletSecret) {
       throw new Error("named task routes require apiKey, walletId, and walletSecret");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xytara",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Machine commerce SDK for discovery, quoting, execution, lifecycle inspection, and adapters.",
   "main": "index.js",
   "type": "commonjs",

package/server.js

@@ -1414,6 +1414,104 @@ function buildPreparedContinuationAdapterBridgeCarry(portableHandoff, continuati
   };
 }
 
+function buildPreparedContinuationHandoffSummary(portableHandoff, continuation) {
+  const bridge = buildPreparedContinuationAdapterBridgeSummary(portableHandoff, continuation);
+  return {
+    ok: bridge.ok === true,
+    adapter_bridge_ref: bridge.adapter_bridge_ref || null,
+    handoff_contract_ref: bridge.adapter_bridge_ref ? `handoff.${bridge.adapter_bridge_ref}` : null,
+    stable_handoff_ids: [
+      "prepared_artifact_handoff",
+      "review_handoff_summary",
+      "proof_run"
+    ],
+    stable_handoff_carry: bridge.bridge_carry || {},
+    handoff_ready: bridge.bridge_ready === true,
+    next_surface: "/v1/proof-center/result-package-handoff/review/handoff-continuity"
+  };
+}
+
+function buildPreparedContinuationHandoffTemplate(portableHandoff, continuation) {
+  const handoff = portableHandoff && typeof portableHandoff === "object" ? portableHandoff : {};
+  const summary = buildPreparedContinuationHandoffSummary(portableHandoff, continuation);
+  return {
+    ok: true,
+    handoff_contract_ref: summary.handoff_contract_ref || null,
+    target_surface: "/v1/proof-center/result-package-handoff/review/handoff-continuity",
+    request_template: {
+      handoff_bundle: handoff
+    },
+    stable_boundary_ids: [
+      "prepared_artifact_handoff",
+      "review_handoff_summary",
+      "proof_run"
+    ]
+  };
+}
+
+function buildPreparedContinuationHandoffBundle(portableHandoff, continuation) {
+  return {
+    ok: true,
+    handoff_summary: buildPreparedContinuationHandoffSummary(portableHandoff, continuation),
+    handoff_template: buildPreparedContinuationHandoffTemplate(portableHandoff, continuation)
+  };
+}
+
+function buildPreparedContinuationHandoffCarry(portableHandoff, continuation) {
+  const summary = buildPreparedContinuationHandoffSummary(portableHandoff, continuation);
+  return {
+    ok: true,
+    handoff_contract_ref: summary.handoff_contract_ref || null,
+    stable_handoff_ids: Array.isArray(summary.stable_handoff_ids) ? summary.stable_handoff_ids : [],
+    stable_handoff_carry: summary.stable_handoff_carry || {},
+    handoff_ready: summary.handoff_ready === true,
+    review_surface: "/v1/proof-center/result-package-handoff/review/handoff-run"
+  };
+}
+
+function buildPreparedContinuationAdapterConsumableHandoffSummary(portableHandoff, continuation) {
+  const summary = buildPreparedContinuationHandoffSummary(portableHandoff, continuation);
+  return {
+    ok: summary.ok === true,
+    handoff_contract_ref: summary.handoff_contract_ref || null,
+    adapter_handoff_surface_ref: summary.handoff_contract_ref ? `surface.${summary.handoff_contract_ref}` : null,
+    stable_handoff_surface_ids: [
+      "prepared_artifact_handoff_surface",
+      "review_handoff_intake",
+      "proof_run"
+    ],
+    consumable_handoff_carry: summary.stable_handoff_carry || {},
+    adapter_consumable: summary.handoff_ready === true,
+    next_surface: "/v1/proof-center/result-package-handoff/review/handoff-intake"
+  };
+}
+
+function buildPreparedContinuationAdapterConsumableHandoffTemplate(portableHandoff, continuation) {
+  const handoff = portableHandoff && typeof portableHandoff === "object" ? portableHandoff : {};
+  const summary = buildPreparedContinuationAdapterConsumableHandoffSummary(portableHandoff, continuation);
+  return {
+    ok: true,
+    adapter_handoff_surface_ref: summary.adapter_handoff_surface_ref || null,
+    target_surface: "/v1/proof-center/result-package-handoff/review/handoff-intake",
+    request_template: {
+      handoff_bundle: handoff
+    },
+    stable_boundary_ids: [
+      "prepared_artifact_handoff_surface",
+      "review_handoff_intake",
+      "proof_run"
+    ]
+  };
+}
+
+function buildPreparedContinuationAdapterConsumableHandoffBundle(portableHandoff, continuation) {
+  return {
+    ok: true,
+    adapter_handoff_surface_summary: buildPreparedContinuationAdapterConsumableHandoffSummary(portableHandoff, continuation),
+    adapter_handoff_surface_template: buildPreparedContinuationAdapterConsumableHandoffTemplate(portableHandoff, continuation)
+  };
+}
+
 function buildInteractionResultPackageContinuationRequestTemplate(portableHandoff, continuation) {
   const handoff = portableHandoff && typeof portableHandoff === "object" ? portableHandoff : {};
   return {
@@ -2636,6 +2734,223 @@ async function routeRequest(req, res) {
     return;
   }
 
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/handoff-summary") {
+    const body = await readJsonBody(req);
+    const continuationRef = String(body && body.continuation_ref || "").trim();
+    const continuation = getInteractionResultPackageContinuation(continuationRef);
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const resultPackage = getInteractionResultPackage(continuation.result_package_ref);
+    if (!resultPackage) {
+      sendJson(res, 404, { ok: false, error: "result_package_not_found" });
+      return;
+    }
+    const payload = buildInteractionSpinePathRunPayload({
+      ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
+      spine_path_ref: resultPackage.source_ref
+    });
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    const portableHandoff = buildInteractionResultPackagePortableHandoff(result.payload, resultPackage);
+    sendJson(res, 200, buildPreparedContinuationHandoffSummary(portableHandoff, continuation));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/handoff-template") {
+    const body = await readJsonBody(req);
+    const continuationRef = String(body && body.continuation_ref || "").trim();
+    const continuation = getInteractionResultPackageContinuation(continuationRef);
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const resultPackage = getInteractionResultPackage(continuation.result_package_ref);
+    if (!resultPackage) {
+      sendJson(res, 404, { ok: false, error: "result_package_not_found" });
+      return;
+    }
+    const payload = buildInteractionSpinePathRunPayload({
+      ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
+      spine_path_ref: resultPackage.source_ref
+    });
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    const portableHandoff = buildInteractionResultPackagePortableHandoff(result.payload, resultPackage);
+    sendJson(res, 200, buildPreparedContinuationHandoffTemplate(portableHandoff, continuation));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/handoff-bundle") {
+    const body = await readJsonBody(req);
+    const continuationRef = String(body && body.continuation_ref || "").trim();
+    const continuation = getInteractionResultPackageContinuation(continuationRef);
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const resultPackage = getInteractionResultPackage(continuation.result_package_ref);
+    if (!resultPackage) {
+      sendJson(res, 404, { ok: false, error: "result_package_not_found" });
+      return;
+    }
+    const payload = buildInteractionSpinePathRunPayload({
+      ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
+      spine_path_ref: resultPackage.source_ref
+    });
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    const portableHandoff = buildInteractionResultPackagePortableHandoff(result.payload, resultPackage);
+    sendJson(res, 200, buildPreparedContinuationHandoffBundle(portableHandoff, continuation));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/handoff-carry") {
+    const body = await readJsonBody(req);
+    const continuationRef = String(body && body.continuation_ref || "").trim();
+    const continuation = getInteractionResultPackageContinuation(continuationRef);
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const resultPackage = getInteractionResultPackage(continuation.result_package_ref);
+    if (!resultPackage) {
+      sendJson(res, 404, { ok: false, error: "result_package_not_found" });
+      return;
+    }
+    const payload = buildInteractionSpinePathRunPayload({
+      ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
+      spine_path_ref: resultPackage.source_ref
+    });
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    const portableHandoff = buildInteractionResultPackagePortableHandoff(result.payload, resultPackage);
+    sendJson(res, 200, buildPreparedContinuationHandoffCarry(portableHandoff, continuation));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/handoff-surface-summary") {
+    const body = await readJsonBody(req);
+    const continuationRef = String(body && body.continuation_ref || "").trim();
+    const continuation = getInteractionResultPackageContinuation(continuationRef);
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const resultPackage = getInteractionResultPackage(continuation.result_package_ref);
+    if (!resultPackage) {
+      sendJson(res, 404, { ok: false, error: "result_package_not_found" });
+      return;
+    }
+    const payload = buildInteractionSpinePathRunPayload({
+      ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
+      spine_path_ref: resultPackage.source_ref
+    });
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    const portableHandoff = buildInteractionResultPackagePortableHandoff(result.payload, resultPackage);
+    sendJson(res, 200, buildPreparedContinuationAdapterConsumableHandoffSummary(portableHandoff, continuation));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/handoff-surface-template") {
+    const body = await readJsonBody(req);
+    const continuationRef = String(body && body.continuation_ref || "").trim();
+    const continuation = getInteractionResultPackageContinuation(continuationRef);
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const resultPackage = getInteractionResultPackage(continuation.result_package_ref);
+    if (!resultPackage) {
+      sendJson(res, 404, { ok: false, error: "result_package_not_found" });
+      return;
+    }
+    const payload = buildInteractionSpinePathRunPayload({
+      ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
+      spine_path_ref: resultPackage.source_ref
+    });
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    const portableHandoff = buildInteractionResultPackagePortableHandoff(result.payload, resultPackage);
+    sendJson(res, 200, buildPreparedContinuationAdapterConsumableHandoffTemplate(portableHandoff, continuation));
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/handoff-surface-bundle") {
+    const body = await readJsonBody(req);
+    const continuationRef = String(body && body.continuation_ref || "").trim();
+    const continuation = getInteractionResultPackageContinuation(continuationRef);
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const resultPackage = getInteractionResultPackage(continuation.result_package_ref);
+    if (!resultPackage) {
+      sendJson(res, 404, { ok: false, error: "result_package_not_found" });
+      return;
+    }
+    const payload = buildInteractionSpinePathRunPayload({
+      ...(body && typeof body === "object" && !Array.isArray(body) ? body : {}),
+      spine_path_ref: resultPackage.source_ref
+    });
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    const portableHandoff = buildInteractionResultPackagePortableHandoff(result.payload, resultPackage);
+    sendJson(res, 200, buildPreparedContinuationAdapterConsumableHandoffBundle(portableHandoff, continuation));
+    return;
+  }
+
   if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare/contract-template") {
     const body = await readJsonBody(req);
     const continuationRef = String(body && body.continuation_ref || "").trim();