xytara 1.9.0 → 1.10.0

package/README.md

@@ -130,6 +130,15 @@ The current `1.9.0` line starts hardening the output side of that spine into cle
 
 This is intended to make grouped spine outputs easier to treat as stable artifacts and future adapter-ready boundaries instead of one-off route responses.
 
+The current `1.10.0` line starts building on that by exposing reusable continuation templates on top of result packages:
+
+- result-package continuation catalog, summary, and detail routes
+- direct continuation run surfaces that preserve the default next proof path
+- continuation preparation surfaces that emit proof-ready request templates
+- continuation summaries that make the default transaction-to-proof bridge explicit instead of inferred
+
+This is intended to make the public stack easier to compose after grouped execution, not just easier to inspect.
+
 ## 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.9.0";
+const COMMERCE_SDK_VERSION = "1.10.0";
 const COMMERCE_API_VERSION = "v1";
 
 function createClient(options) {

package/lib/catalog_contract.js

@@ -332,6 +332,31 @@ function buildInteractionResultPackages() {
   }));
 }
 
+function buildInteractionResultPackageContinuationTemplates() {
+  return buildInteractionResultPackages().map((resultPackage) => ({
+    continuation_ref: resultPackage && resultPackage.result_package_ref
+      ? `continue.${resultPackage.result_package_ref}`
+      : null,
+    result_package_ref: resultPackage && resultPackage.result_package_ref ? resultPackage.result_package_ref : null,
+    source_ref: resultPackage && resultPackage.source_ref ? resultPackage.source_ref : null,
+    title: resultPackage && resultPackage.title
+      ? `${resultPackage.title} Continuation`
+      : "Interaction Result Package Continuation",
+    description: resultPackage && resultPackage.description
+      ? `${resultPackage.description} Continue through the reusable default path into proof-native follow-through.`
+      : "Continue through the reusable default path into proof-native follow-through.",
+    continuation_kind: "proof_native_default",
+    default_next_surface: "/v1/transaction-center/result-package-continuations/run",
+    default_export_surface: "/v1/transaction-center/result-packages/export",
+    default_proof_surface: "/v1/proof-center/result-package-handoff/run",
+    committed_ref: resultPackage && resultPackage.committed_ref ? resultPackage.committed_ref : null,
+    precommit_pack_ref: resultPackage && resultPackage.precommit_pack_ref ? resultPackage.precommit_pack_ref : null,
+    seam_layers: Array.isArray(resultPackage && resultPackage.seam_layers) ? resultPackage.seam_layers : [],
+    required_inputs: Array.isArray(resultPackage && resultPackage.required_inputs) ? resultPackage.required_inputs : [],
+    optional_inputs: Array.isArray(resultPackage && resultPackage.optional_inputs) ? resultPackage.optional_inputs : []
+  }));
+}
+
 function buildDefaultTransactionCenter() {
   const settlementProfiles = Array.isArray(catalog.settlement_profiles) ? catalog.settlement_profiles : [];
   const defaultSettlementProfile = settlementProfiles[0] || null;
@@ -590,6 +615,20 @@ function buildInteractionResultPackageCatalog() {
   };
 }
 
+function buildInteractionResultPackageContinuationCatalog() {
+  const center = buildDefaultTransactionCenter();
+  const templates = buildInteractionResultPackageContinuationTemplates();
+  return {
+    ok: true,
+    brand: center.brand,
+    product: "interaction result package continuations",
+    default_payment_protocol: center.default_payment && center.default_payment.protocol ? center.default_payment.protocol : null,
+    default_settlement_mode: center.default_settlement && center.default_settlement.settlement_mode ? center.default_settlement.settlement_mode : null,
+    continuation_count: templates.length,
+    continuations: templates
+  };
+}
+
 function summarizeTransactionClassPacks() {
   const catalogResponse = buildTransactionClassPackCatalog();
   const packs = Array.isArray(catalogResponse.class_packs) ? catalogResponse.class_packs : [];
@@ -655,6 +694,22 @@ function summarizeInteractionResultPackages() {
   };
 }
 
+function summarizeInteractionResultPackageContinuations() {
+  const catalogResponse = buildInteractionResultPackageContinuationCatalog();
+  const templates = Array.isArray(catalogResponse.continuations) ? catalogResponse.continuations : [];
+  return {
+    ok: true,
+    brand: catalogResponse.brand,
+    product: catalogResponse.product,
+    default_payment_protocol: catalogResponse.default_payment_protocol,
+    default_settlement_mode: catalogResponse.default_settlement_mode,
+    continuation_count: templates.length,
+    continuation_refs: templates.map((entry) => entry && entry.continuation_ref).filter(Boolean),
+    result_package_refs: templates.map((entry) => entry && entry.result_package_ref).filter(Boolean),
+    continuations: templates
+  };
+}
+
 function getTransactionClassPack(ref) {
   const normalized = String(ref || "").trim();
   if (!normalized) return null;
@@ -679,6 +734,12 @@ function getInteractionResultPackage(ref) {
   return buildInteractionResultPackages().find((entry) => entry && entry.result_package_ref === normalized) || null;
 }
 
+function getInteractionResultPackageContinuation(ref) {
+  const normalized = String(ref || "").trim();
+  if (!normalized) return null;
+  return buildInteractionResultPackageContinuationTemplates().find((entry) => entry && entry.continuation_ref === normalized) || null;
+}
+
 function buildCatalogResponse() {
   return {
     ok: true,
@@ -814,6 +875,7 @@ module.exports = {
   buildDefaultTransactionCenter,
   buildDefaultTransactionGuidedLoopCatalog,
   buildInteractionResultPackageCatalog,
+  buildInteractionResultPackageContinuationCatalog,
   buildInteractionSpinePathCatalog,
   buildPrecommitInteractionPackCatalog,
   buildDefaultTransactionTaskPackCatalog,
@@ -822,6 +884,7 @@ module.exports = {
   getDefaultTransactionGuidedLoop,
   getDefaultTransactionTaskPack,
   getInteractionResultPackage,
+  getInteractionResultPackageContinuation,
   getInteractionSpinePath,
   getPrecommitInteractionPack,
   getTransactionClassPack,
@@ -833,6 +896,7 @@ module.exports = {
   summarizeDefaultTransactionEconomics,
   summarizeDefaultTransactionGuidedLoops,
   summarizeDefaultTransactionTaskPacks,
+  summarizeInteractionResultPackageContinuations,
   summarizeInteractionResultPackages,
   summarizeInteractionSpinePaths,
   summarizePrecommitInteractionPacks,

package/lib/commerce_client.js

@@ -1139,6 +1139,46 @@ function summarizeInteractionResultPackagePortableHandoffPayload(payload) {
   };
 }
 
+function summarizeInteractionResultPackageContinuationPayload(payload) {
+  const item = payload && typeof payload === "object" ? payload : {};
+  return {
+    ok: item.ok === true,
+    continuation_ref: item.continuation_ref || null,
+    result_package_ref: item.result_package_ref || null,
+    source_ref: item.source_ref || null,
+    continuation_kind: item.continuation_kind || null,
+    default_next_surface: item.default_next_surface || null,
+    default_export_surface: item.default_export_surface || null,
+    default_proof_surface: item.default_proof_surface || null,
+    transaction_id: item.transaction_id || null,
+    receipt_id: item.receipt_id || null,
+    proof_ref: item.proof_ref || null,
+    continuation_ready: item.continuation_ready === true,
+    seam_layer_count: Number(item.seam_layer_count || 0)
+  };
+}
+
+function summarizeInteractionResultPackageContinuationPreparationPayload(payload) {
+  const item = payload && typeof payload === "object" ? payload : {};
+  const continuation = item.continuation_summary && typeof item.continuation_summary === "object"
+    ? summarizeInteractionResultPackageContinuationPayload(item.continuation_summary)
+    : null;
+  const template = item.proof_request_template && typeof item.proof_request_template === "object"
+    ? item.proof_request_template
+    : {};
+  return {
+    ok: item.ok === true,
+    continuation_ref: continuation ? continuation.continuation_ref : null,
+    result_package_ref: continuation ? continuation.result_package_ref : null,
+    target_surface: template.target_surface || null,
+    review_surface: template.review_surface || null,
+    continuation_ready: continuation ? continuation.continuation_ready === true : false,
+    evidence_ref_count: Array.isArray(template.request_template && template.request_template.evidence_refs)
+      ? template.request_template.evidence_refs.length
+      : 0
+  };
+}
+
 function buildCatalogSummarySource(client) {
   const baseCatalog = client && client.catalogCache && typeof client.catalogCache === "object"
     ? client.catalogCache
@@ -2781,6 +2821,30 @@ class CommerceClient {
     return result && result.data ? result.data : null;
   }
 
+  async getInteractionResultPackageContinuations(forceRefresh) {
+    if (!forceRefresh && this.catalogSummaryCache && this.catalogSummaryCache.resultPackageContinuations) {
+      return this.catalogSummaryCache.resultPackageContinuations;
+    }
+    const result = await this.getJson("/v1/transaction-center/result-package-continuations");
+    if (!forceRefresh) {
+      this.catalogSummaryCache = this.catalogSummaryCache || {};
+      this.catalogSummaryCache.resultPackageContinuations = result.data;
+    }
+    return result.data;
+  }
+
+  async getInteractionResultPackageContinuationsSummary(forceRefresh) {
+    const result = await this.getJson("/v1/transaction-center/result-package-continuations/summary");
+    return result && result.data ? result.data : { ok: true, continuation_count: 0, continuation_refs: [], continuations: [] };
+  }
+
+  async getInteractionResultPackageContinuation(continuationRef, forceRefresh) {
+    const normalized = String(continuationRef || "").trim();
+    if (!normalized) return null;
+    const result = await this.getJson(`/v1/transaction-center/result-package-continuation?ref=${encodeURIComponent(normalized)}`);
+    return result && result.data && result.data.continuation ? result.data.continuation : null;
+  }
+
   async listSettlementPayees(forceRefresh) {
     const summary = await this.getSettlementPayeeSummaries(forceRefresh);
     return extractSummaryValues(summary, "settlement_payees", "payee_agent_id");
@@ -4171,6 +4235,66 @@ class CommerceClient {
     };
   }
 
+  async runInteractionResultPackageContinuation(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/run", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.run",
+      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 runInteractionResultPackageContinuationSummary(continuationRef, body, options) {
+    const result = await this.runInteractionResultPackageContinuation(continuationRef, body, options);
+    return {
+      ok: result && result.ok === true,
+      continuation_ref: result && result.continuation ? result.continuation.continuation_ref || null : null,
+      result_package_ref: result && result.result_package ? result.result_package.result_package_ref || null : null,
+      continuation_summary: this.summarizeInteractionResultPackageContinuation(
+        result && result.continuation_summary ? result.continuation_summary : null
+      ),
+      portable_handoff_summary: this.summarizeInteractionResultPackagePortableHandoff(
+        result && result.portable_handoff_summary ? result.portable_handoff_summary : null
+      ),
+      seam_summary: result && result.seam_summary ? {
+        ...result.seam_summary,
+        proof_handoff_summary: this.summarizeProofHandoff(
+          result.seam_summary && result.seam_summary.proof_handoff_summary
+            ? result.seam_summary.proof_handoff_summary
+            : null
+        )
+      } : null
+    };
+  }
+
+  async prepareInteractionResultPackageContinuation(continuationRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/result-package-continuations/prepare", {
+      command: opts.command || String(continuationRef || "").trim() || "result.package.continuation.prepare",
+      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 prepareInteractionResultPackageContinuationSummary(continuationRef, body, options) {
+    const result = await this.prepareInteractionResultPackageContinuation(continuationRef, body, options);
+    return summarizeInteractionResultPackageContinuationPreparationPayload(result);
+  }
+
   async runNamedTaskRoute(path, payload) {
     if (!this.apiKey || !this.walletId || !this.walletSecret) {
       throw new Error("named task routes require apiKey, walletId, and walletSecret");
@@ -5678,6 +5802,14 @@ class CommerceClient {
     return summarizeInteractionResultPackagePortableHandoffPayload(payload);
   }
 
+  summarizeInteractionResultPackageContinuation(payload) {
+    return summarizeInteractionResultPackageContinuationPayload(payload);
+  }
+
+  summarizeInteractionResultPackageContinuationPreparation(payload) {
+    return summarizeInteractionResultPackageContinuationPreparationPayload(payload);
+  }
+
   summarizeTask(task) {
     return summarizeCatalogTask(task);
   }
@@ -6431,6 +6563,8 @@ module.exports = {
   summarizeQuotePreviewPayload,
   summarizeDefaultTransactionCenterPayload,
   summarizeDefaultTransactionEconomicsPayload,
+  summarizeInteractionResultPackageContinuationPayload,
+  summarizeInteractionResultPackageContinuationPreparationPayload,
   summarizeInteractionResultPackagePayload,
   summarizeInteractionResultPackagePortableHandoffPayload,
   summarizeDefaultTaskPackCatalogPayload,

package/package.json

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

package/server.js

@@ -8,6 +8,7 @@ const {
   buildDefaultTransactionEconomics,
   buildDefaultTransactionGuidedLoopCatalog,
   buildInteractionResultPackageCatalog,
+  buildInteractionResultPackageContinuationCatalog,
   buildInteractionSpinePathCatalog,
   buildPrecommitInteractionPackCatalog,
   buildDefaultTransactionTaskPackCatalog,
@@ -16,6 +17,7 @@ const {
   getDefaultTransactionGuidedLoop,
   getDefaultTransactionTaskPack,
   getInteractionResultPackage,
+  getInteractionResultPackageContinuation,
   getInteractionSpinePath,
   getPrecommitInteractionPack,
   getTransactionClassPack,
@@ -26,6 +28,7 @@ const {
   summarizeDefaultTransactionCenter,
   summarizeDefaultTransactionEconomics,
   summarizeDefaultTransactionGuidedLoops,
+  summarizeInteractionResultPackageContinuations,
   summarizeInteractionResultPackages,
   summarizeInteractionSpinePaths,
   summarizeDefaultTransactionTaskPacks,
@@ -1087,6 +1090,42 @@ function summarizeInteractionResultPackagePortableHandoff(handoff) {
   };
 }
 
+function buildInteractionResultPackageContinuationSummary(portableHandoff, continuation) {
+  const handoff = portableHandoff && typeof portableHandoff === "object" ? portableHandoff : {};
+  return {
+    ok: true,
+    continuation_ref: continuation && continuation.continuation_ref ? continuation.continuation_ref : null,
+    result_package_ref: continuation && continuation.result_package_ref ? continuation.result_package_ref : null,
+    source_ref: continuation && continuation.source_ref ? continuation.source_ref : null,
+    continuation_kind: continuation && continuation.continuation_kind ? continuation.continuation_kind : null,
+    default_next_surface: continuation && continuation.default_next_surface ? continuation.default_next_surface : null,
+    default_export_surface: continuation && continuation.default_export_surface ? continuation.default_export_surface : null,
+    default_proof_surface: continuation && continuation.default_proof_surface ? continuation.default_proof_surface : null,
+    transaction_id: handoff.transaction_id || null,
+    receipt_id: handoff.receipt_id || null,
+    proof_ref: handoff.proof_ref || null,
+    continuation_ready: Boolean(handoff.result_package_ref && handoff.proof_ref),
+    seam_layer_count: Array.isArray(handoff.seam_layers) ? handoff.seam_layers.length : 0
+  };
+}
+
+function buildInteractionResultPackageContinuationRequestTemplate(portableHandoff, continuation) {
+  const handoff = portableHandoff && typeof portableHandoff === "object" ? portableHandoff : {};
+  return {
+    ok: true,
+    continuation_ref: continuation && continuation.continuation_ref ? continuation.continuation_ref : null,
+    target_surface: "/v1/proof-center/result-package-handoff/run",
+    review_surface: "/v1/proof-center/result-package-handoff/review",
+    request_template: {
+      handoff_bundle: handoff,
+      evidence_refs: handoff.proof_ref ? [handoff.proof_ref] : [],
+      options: {
+        legacy_identity_material_hex: "<required_for_local_demo_signing>"
+      }
+    }
+  };
+}
+
 function buildOperationsDashboard(filters) {
   const disputes = listRecords(state.disputes, filters);
   const refunds = listRecords(state.refunds, filters);
@@ -1274,6 +1313,26 @@ async function routeRequest(req, res) {
     return;
   }
 
+  if (req.method === "GET" && url.pathname === "/v1/transaction-center/result-package-continuations") {
+    sendJson(res, 200, buildInteractionResultPackageContinuationCatalog());
+    return;
+  }
+
+  if (req.method === "GET" && url.pathname === "/v1/transaction-center/result-package-continuations/summary") {
+    sendJson(res, 200, summarizeInteractionResultPackageContinuations());
+    return;
+  }
+
+  if (req.method === "GET" && url.pathname === "/v1/transaction-center/result-package-continuation") {
+    const continuation = getInteractionResultPackageContinuation(url.searchParams.get("ref"));
+    if (!continuation) {
+      sendJson(res, 404, { ok: false, error: "result_package_continuation_not_found" });
+      return;
+    }
+    sendJson(res, 200, { ok: true, continuation });
+    return;
+  }
+
   if (req.method === "GET" && url.pathname === "/v1/transaction-center/transaction-class-packs") {
     sendJson(res, 200, buildTransactionClassPackCatalog());
     return;
@@ -1929,6 +1988,86 @@ async function routeRequest(req, res) {
     return;
   }
 
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/run") {
+    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, {
+      ok: true,
+      continuation,
+      result_package: resultPackage,
+      result: result.payload,
+      result_package_summary: buildInteractionResultPackageSummary(result.payload, resultPackage),
+      portable_handoff_bundle: portableHandoff,
+      portable_handoff_summary: summarizeInteractionResultPackagePortableHandoff(portableHandoff),
+      continuation_summary: buildInteractionResultPackageContinuationSummary(portableHandoff, continuation),
+      seam_summary: buildInteractionResultSeamSummary(result.payload, resultPackage)
+    });
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/result-package-continuations/prepare") {
+    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, {
+      ok: true,
+      continuation,
+      result_package: resultPackage,
+      result_package_summary: buildInteractionResultPackageSummary(result.payload, resultPackage),
+      portable_handoff_summary: summarizeInteractionResultPackagePortableHandoff(portableHandoff),
+      continuation_summary: buildInteractionResultPackageContinuationSummary(portableHandoff, continuation),
+      proof_request_template: buildInteractionResultPackageContinuationRequestTemplate(portableHandoff, continuation)
+    });
+    return;
+  }
+
   if (req.method === "POST" && url.pathname === "/v1/transaction-center/default-loops/run") {
     const body = await readJsonBody(req);
     const loopRef = String(body && body.loop_ref || "").trim();