xytara 1.6.0 → 1.7.0

package/README.md

@@ -97,6 +97,14 @@ The next `1.6.0` carry also adds guided default loops on top of those packs:
 
 That means the first-party path is easier to both run and inspect without manually stitching together monitor, receipt, delivery, and payment-ledger helpers after execution.
 
+The current `1.7.0` line starts widening that surface into real grouped transaction classes:
+
+- transaction-class pack catalog, summary, and detail routes
+- grouped transaction-class run routes for first-party commerce classes
+- proof-handoff summaries that make the next step into `xoonya` more obvious from transaction outputs
+
+This is the first step beyond “clear default loop” toward “broader useful machine-commerce classes plus clearer commerce-to-proof follow-through.”
+
 ## 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.6.0";
+const COMMERCE_SDK_VERSION = "1.7.0";
 const COMMERCE_API_VERSION = "v1";
 
 function createClient(options) {

package/lib/catalog_contract.js

@@ -110,6 +110,83 @@ function buildDefaultTransactionGuidedLoops() {
   ];
 }
 
+function buildTransactionClassPacks() {
+  const center = buildDefaultTransactionCenter();
+  const defaultSettlementMode = center.default_settlement && center.default_settlement.settlement_mode
+    ? center.default_settlement.settlement_mode
+    : null;
+  const defaultPaymentProtocol = center.default_payment && center.default_payment.protocol
+    ? center.default_payment.protocol
+    : null;
+  return [
+    {
+      class_pack_ref: "transaction.trust.receipt",
+      title: "Trust Receipt Transaction",
+      description: "Verify trust posture and validate the paired receipt as one grouped transaction class.",
+      workflow_ref: "trust.flow",
+      task_refs: ["trust.verify", "receipt.validate"],
+      category: "trust",
+      proof_handoff_kind: "receipt_validation",
+      default_payment_protocol: defaultPaymentProtocol,
+      default_settlement_mode: defaultSettlementMode,
+      required_inputs: ["subject_id", "receipt_id"],
+      optional_inputs: ["payment_protocol", "settlement_mode"]
+    },
+    {
+      class_pack_ref: "transaction.runtime.consequence",
+      title: "Runtime Consequence Transaction",
+      description: "Emit a runtime consequence and anchor the resulting commitment as one grouped transaction class.",
+      workflow_ref: "runtime.consequence.flow",
+      task_refs: ["runtime.emit", "runtime.anchor"],
+      category: "runtime",
+      proof_handoff_kind: "runtime_anchor",
+      default_payment_protocol: defaultPaymentProtocol,
+      default_settlement_mode: defaultSettlementMode,
+      required_inputs: ["intent_id", "event_type", "event_commitment"],
+      optional_inputs: ["payment_protocol", "settlement_mode"]
+    },
+    {
+      class_pack_ref: "transaction.admission.settlement",
+      title: "Admission Settlement Transaction",
+      description: "Preview admission and submit settlement as one grouped transaction class.",
+      workflow_ref: "admission.settlement.flow",
+      task_refs: ["admission.preview", "settlement.submit"],
+      category: "admission",
+      proof_handoff_kind: "admission_settlement",
+      default_payment_protocol: defaultPaymentProtocol,
+      default_settlement_mode: defaultSettlementMode,
+      required_inputs: ["source_zone_id", "target_zone_id", "intent_id"],
+      optional_inputs: ["interaction_class", "payment_protocol", "settlement_mode"]
+    },
+    {
+      class_pack_ref: "transaction.registry.anchor",
+      title: "Registry Anchor Transaction",
+      description: "Register a record and anchor its commitment as one grouped transaction class.",
+      workflow_ref: "registry.anchor.flow",
+      task_refs: ["registry.register", "anchoring.submit"],
+      category: "registry",
+      proof_handoff_kind: "registry_anchor",
+      default_payment_protocol: defaultPaymentProtocol,
+      default_settlement_mode: defaultSettlementMode,
+      required_inputs: ["subject_id", "record_type", "commitment_hash"],
+      optional_inputs: ["payment_protocol", "settlement_mode"]
+    },
+    {
+      class_pack_ref: "transaction.job.commitment",
+      title: "Job Commitment Transaction",
+      description: "Quote, reserve, and commit a job as one grouped transaction class.",
+      workflow_ref: "job.commitment.flow",
+      task_refs: ["jobs.quote", "jobs.reserve", "jobs.commit"],
+      category: "jobs",
+      proof_handoff_kind: "job_commitment",
+      default_payment_protocol: defaultPaymentProtocol,
+      default_settlement_mode: defaultSettlementMode,
+      required_inputs: ["job_type", "job_id"],
+      optional_inputs: ["payment_protocol", "settlement_mode"]
+    }
+  ];
+}
+
 function buildDefaultTransactionCenter() {
   const settlementProfiles = Array.isArray(catalog.settlement_profiles) ? catalog.settlement_profiles : [];
   const defaultSettlementProfile = settlementProfiles[0] || null;
@@ -312,6 +389,42 @@ function getDefaultTransactionGuidedLoop(ref) {
   return buildDefaultTransactionGuidedLoops().find((entry) => entry && entry.loop_ref === normalized) || null;
 }
 
+function buildTransactionClassPackCatalog() {
+  const center = buildDefaultTransactionCenter();
+  const packs = buildTransactionClassPacks();
+  return {
+    ok: true,
+    brand: center.brand,
+    product: "transaction class packs",
+    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,
+    class_pack_count: packs.length,
+    class_packs: packs
+  };
+}
+
+function summarizeTransactionClassPacks() {
+  const catalogResponse = buildTransactionClassPackCatalog();
+  const packs = Array.isArray(catalogResponse.class_packs) ? catalogResponse.class_packs : [];
+  return {
+    ok: true,
+    brand: catalogResponse.brand,
+    product: catalogResponse.product,
+    default_payment_protocol: catalogResponse.default_payment_protocol,
+    default_settlement_mode: catalogResponse.default_settlement_mode,
+    class_pack_count: packs.length,
+    class_pack_refs: packs.map((entry) => entry && entry.class_pack_ref).filter(Boolean),
+    categories: Array.from(new Set(packs.map((entry) => entry && entry.category).filter(Boolean))),
+    class_packs: packs
+  };
+}
+
+function getTransactionClassPack(ref) {
+  const normalized = String(ref || "").trim();
+  if (!normalized) return null;
+  return buildTransactionClassPacks().find((entry) => entry && entry.class_pack_ref === normalized) || null;
+}
+
 function buildCatalogResponse() {
   return {
     ok: true,
@@ -447,9 +560,11 @@ module.exports = {
   buildDefaultTransactionCenter,
   buildDefaultTransactionGuidedLoopCatalog,
   buildDefaultTransactionTaskPackCatalog,
+  buildTransactionClassPackCatalog,
   getCatalog,
   getDefaultTransactionGuidedLoop,
   getDefaultTransactionTaskPack,
+  getTransactionClassPack,
   getTaskDetail,
   getWorkflowDetail,
   getWorkflowList,
@@ -457,5 +572,6 @@ module.exports = {
   summarizeDefaultTransactionCenter,
   summarizeDefaultTransactionEconomics,
   summarizeDefaultTransactionGuidedLoops,
-  summarizeDefaultTransactionTaskPacks
+  summarizeDefaultTransactionTaskPacks,
+  summarizeTransactionClassPacks
 };

package/lib/commerce_client.js

@@ -1070,6 +1070,25 @@ function summarizeDefaultGuidedLoopBundlePayload(payload) {
   };
 }
 
+function summarizeProofHandoffPayload(payload) {
+  const item = payload && typeof payload === "object" ? payload : {};
+  const bundle = item.handoff_bundle && typeof item.handoff_bundle === "object" ? item.handoff_bundle : {};
+  return {
+    ok: item.ok === true,
+    source_ref: item.source_ref || null,
+    transaction_id: item.transaction_id || null,
+    receipt_id: item.receipt_id || null,
+    proof_ref: item.proof_ref || null,
+    settlement_mode: item.settlement_mode || null,
+    payment_protocol: item.payment_protocol || null,
+    proof_ready: item.proof_ready === true,
+    recommended_proof_loop: item.recommended_proof_loop || null,
+    delivery_count: Number(bundle.delivery_count || 0),
+    payment_ledger_count: Number(bundle.payment_ledger_count || 0),
+    task_refs: Array.isArray(bundle.task_refs) ? bundle.task_refs : []
+  };
+}
+
 function buildCatalogSummarySource(client) {
   const baseCatalog = client && client.catalogCache && typeof client.catalogCache === "object"
     ? client.catalogCache
@@ -2609,6 +2628,30 @@ class CommerceClient {
     return result && result.data && result.data.loop ? result.data.loop : null;
   }
 
+  async getTransactionClassPacks(forceRefresh) {
+    if (!forceRefresh && this.catalogSummaryCache && this.catalogSummaryCache.transactionClassPacks) {
+      return this.catalogSummaryCache.transactionClassPacks;
+    }
+    const result = await this.getJson("/v1/transaction-center/transaction-class-packs");
+    if (!forceRefresh) {
+      this.catalogSummaryCache = this.catalogSummaryCache || {};
+      this.catalogSummaryCache.transactionClassPacks = result.data;
+    }
+    return result.data;
+  }
+
+  async getTransactionClassPacksSummary(forceRefresh) {
+    const result = await this.getJson("/v1/transaction-center/transaction-class-packs/summary");
+    return result && result.data ? result.data : { ok: true, class_pack_count: 0, class_pack_refs: [], class_packs: [] };
+  }
+
+  async getTransactionClassPack(classPackRef, forceRefresh) {
+    const normalized = String(classPackRef || "").trim();
+    if (!normalized) return null;
+    const result = await this.getJson(`/v1/transaction-center/transaction-class-pack?ref=${encodeURIComponent(normalized)}`);
+    return result && result.data && result.data.class_pack ? result.data.class_pack : null;
+  }
+
   async listSettlementPayees(forceRefresh) {
     const summary = await this.getSettlementPayeeSummaries(forceRefresh);
     return extractSummaryValues(summary, "settlement_payees", "payee_agent_id");
@@ -3834,6 +3877,35 @@ class CommerceClient {
     return this.summarizeDefaultGuidedLoopBundle(result);
   }
 
+  async runTransactionClassPack(classPackRef, body, options) {
+    const opts = options || {};
+    return this.runNamedTaskRoute("/v1/transaction-center/transaction-class-packs/run", {
+      command: opts.command || String(classPackRef || "").trim() || "transaction.class.pack.run",
+      class_pack_ref: String(classPackRef || "").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 runTransactionClassPackSummary(classPackRef, body, options) {
+    const result = await this.runTransactionClassPack(classPackRef, body, options);
+    return {
+      ok: result && result.ok === true,
+      class_pack_ref: result && result.class_pack ? result.class_pack.class_pack_ref || null : null,
+      workflow_ref: result && result.class_pack ? result.class_pack.workflow_ref || null : null,
+      result_set_summary: result && result.result_set_summary ? result.result_set_summary : null,
+      linked_record_summary: result && result.linked_record_summary ? result.linked_record_summary : null,
+      activity_summary: result && result.activity_summary ? result.activity_summary : null,
+      proof_handoff_summary: this.summarizeProofHandoff(result && result.proof_handoff_summary ? result.proof_handoff_summary : null)
+    };
+  }
+
   async runNamedTaskRoute(path, payload) {
     if (!this.apiKey || !this.walletId || !this.walletSecret) {
       throw new Error("named task routes require apiKey, walletId, and walletSecret");
@@ -5329,6 +5401,10 @@ class CommerceClient {
     return summarizeDefaultGuidedLoopBundlePayload(payload);
   }
 
+  summarizeProofHandoff(payload) {
+    return summarizeProofHandoffPayload(payload);
+  }
+
   summarizeTask(task) {
     return summarizeCatalogTask(task);
   }
@@ -6084,6 +6160,7 @@ module.exports = {
   summarizeDefaultTransactionEconomicsPayload,
   summarizeDefaultTaskPackCatalogPayload,
   summarizeDefaultGuidedLoopBundlePayload,
+  summarizeProofHandoffPayload,
   summarizeActivitySnapshotPayload,
   summarizeOpenIssuesPayload,
   summarizeExecutionExceptionsPayload,

package/package.json

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

package/server.js

@@ -8,9 +8,11 @@ const {
   buildDefaultTransactionEconomics,
   buildDefaultTransactionGuidedLoopCatalog,
   buildDefaultTransactionTaskPackCatalog,
+  buildTransactionClassPackCatalog,
   getCatalog,
   getDefaultTransactionGuidedLoop,
   getDefaultTransactionTaskPack,
+  getTransactionClassPack,
   getTaskDetail,
   getWorkflowDetail,
   getWorkflowList,
@@ -18,7 +20,8 @@ const {
   summarizeDefaultTransactionCenter,
   summarizeDefaultTransactionEconomics,
   summarizeDefaultTransactionGuidedLoops,
-  summarizeDefaultTransactionTaskPacks
+  summarizeDefaultTransactionTaskPacks,
+  summarizeTransactionClassPacks
 } = require("./lib/catalog_contract");
 const {
   createCommandResult,
@@ -364,6 +367,145 @@ function buildDefaultTransactionTaskPackInvokePayload(body) {
   return null;
 }
 
+function buildTransactionClassPackRunPayload(body) {
+  const requestBody = body && typeof body === "object" && !Array.isArray(body) ? body : {};
+  const packBody = requestBody.body && typeof requestBody.body === "object" && !Array.isArray(requestBody.body)
+    ? requestBody.body
+    : requestBody;
+  const classPackRef = String(requestBody.class_pack_ref || "").trim();
+  const integrationIds = Array.isArray(requestBody.integration_ids) && requestBody.integration_ids.length > 0
+    ? requestBody.integration_ids
+    : ["builtin.payment.x402", "builtin.settlement.chain"];
+
+  if (classPackRef === "transaction.trust.receipt") {
+    return buildNamedTaskSetPayload([
+      {
+        task_id: "task_1",
+        task_ref: "trust.verify",
+        body: { subject_id: packBody.subject_id }
+      },
+      {
+        task_id: "task_2",
+        task_ref: "receipt.validate",
+        body: { receipt_id: packBody.receipt_id }
+      }
+    ], {
+      ...requestBody,
+      ...packBody,
+      payment_protocol: requestBody.payment_protocol || "x402",
+      integration_ids: integrationIds,
+      settlement_mode: requestBody.settlement_mode || "evm_payment"
+    }, requestBody.command || classPackRef);
+  }
+
+  if (classPackRef === "transaction.runtime.consequence") {
+    return buildNamedTaskSetPayload([
+      {
+        task_id: "task_1",
+        task_ref: "runtime.emit",
+        body: {
+          intent_id: packBody.intent_id,
+          event_type: packBody.event_type
+        }
+      },
+      {
+        task_id: "task_2",
+        task_ref: "runtime.anchor",
+        body: {
+          event_commitment: packBody.event_commitment
+        }
+      }
+    ], {
+      ...requestBody,
+      ...packBody,
+      payment_protocol: requestBody.payment_protocol || "x402",
+      integration_ids: integrationIds,
+      settlement_mode: requestBody.settlement_mode || "evm_payment"
+    }, requestBody.command || classPackRef);
+  }
+
+  if (classPackRef === "transaction.admission.settlement") {
+    return buildNamedTaskSetPayload([
+      {
+        task_id: "task_1",
+        task_ref: "admission.preview",
+        body: {
+          source_zone_id: packBody.source_zone_id,
+          target_zone_id: packBody.target_zone_id,
+          interaction_class: packBody.interaction_class
+        }
+      },
+      {
+        task_id: "task_2",
+        task_ref: "settlement.submit",
+        body: {
+          intent_id: packBody.intent_id
+        }
+      }
+    ], {
+      ...requestBody,
+      ...packBody,
+      payment_protocol: requestBody.payment_protocol || "x402",
+      integration_ids: integrationIds,
+      settlement_mode: requestBody.settlement_mode || "evm_payment"
+    }, requestBody.command || classPackRef);
+  }
+
+  if (classPackRef === "transaction.registry.anchor") {
+    return buildNamedTaskSetPayload([
+      {
+        task_id: "task_1",
+        task_ref: "registry.register",
+        body: {
+          subject_id: packBody.subject_id,
+          record_type: packBody.record_type
+        }
+      },
+      {
+        task_id: "task_2",
+        task_ref: "anchoring.submit",
+        body: {
+          commitment_hash: packBody.commitment_hash
+        }
+      }
+    ], {
+      ...requestBody,
+      ...packBody,
+      payment_protocol: requestBody.payment_protocol || "x402",
+      integration_ids: integrationIds,
+      settlement_mode: requestBody.settlement_mode || "evm_payment"
+    }, requestBody.command || classPackRef);
+  }
+
+  if (classPackRef === "transaction.job.commitment") {
+    return buildNamedTaskSetPayload([
+      {
+        task_id: "task_1",
+        task_ref: "jobs.quote",
+        body: { job_type: packBody.job_type }
+      },
+      {
+        task_id: "task_2",
+        task_ref: "jobs.reserve",
+        body: { job_id: packBody.job_id }
+      },
+      {
+        task_id: "task_3",
+        task_ref: "jobs.commit",
+        body: { job_id: packBody.job_id }
+      }
+    ], {
+      ...requestBody,
+      ...packBody,
+      payment_protocol: requestBody.payment_protocol || "x402",
+      integration_ids: integrationIds,
+      settlement_mode: requestBody.settlement_mode || "evm_payment"
+    }, requestBody.command || classPackRef);
+  }
+
+  return null;
+}
+
 function listTransactionRecords(filters) {
   const transactions = Array.from(state.transactions.values()).map((item) => item.transaction);
   return listRecords(new Map(transactions.map((item) => [item.transaction_id, item])), filters);
@@ -481,6 +623,35 @@ function buildGuidedLoopBundle(loopRef, result) {
   };
 }
 
+function buildProofHandoffSummary(result, sourceRef) {
+  const resultSet = buildResultSetFromCommandResult(result);
+  const linked = buildLinkedRecordSetFromCommandResult(result);
+  const receipt = resultSet.receipt || {};
+  const transaction = resultSet.transaction || {};
+  return {
+    ok: true,
+    source_ref: sourceRef || null,
+    transaction_id: transaction.transaction_id || null,
+    receipt_id: receipt.receipt_id || null,
+    proof_ref: receipt.proof_ref || null,
+    settlement_mode: transaction.settlement && transaction.settlement.mode ? transaction.settlement.mode : null,
+    payment_protocol: transaction.payment && transaction.payment.protocol ? transaction.payment.protocol : null,
+    proof_ready: Boolean(receipt.receipt_id && receipt.proof_ref),
+    recommended_proof_loop: "default.proof.bundle.loop",
+    recommended_xoonya_surface: "/v1/proof-center/default-loops/run",
+    handoff_bundle: {
+      transaction_id: transaction.transaction_id || null,
+      receipt_id: receipt.receipt_id || null,
+      proof_ref: receipt.proof_ref || null,
+      task_refs: transaction.execution && transaction.execution.results_by_task_id
+        ? Object.values(transaction.execution.results_by_task_id).map((entry) => entry && entry.task_ref).filter(Boolean)
+        : [],
+      delivery_count: Array.isArray(linked.deliveries) ? linked.deliveries.length : 0,
+      payment_ledger_count: Array.isArray(linked.payment_ledger) ? linked.payment_ledger.length : 0
+    }
+  };
+}
+
 function buildOperationsDashboard(filters) {
   const disputes = listRecords(state.disputes, filters);
   const refunds = listRecords(state.refunds, filters);
@@ -589,6 +760,26 @@ async function routeRequest(req, res) {
     return;
   }
 
+  if (req.method === "GET" && url.pathname === "/v1/transaction-center/transaction-class-packs") {
+    sendJson(res, 200, buildTransactionClassPackCatalog());
+    return;
+  }
+
+  if (req.method === "GET" && url.pathname === "/v1/transaction-center/transaction-class-packs/summary") {
+    sendJson(res, 200, summarizeTransactionClassPacks());
+    return;
+  }
+
+  if (req.method === "GET" && url.pathname === "/v1/transaction-center/transaction-class-pack") {
+    const pack = getTransactionClassPack(url.searchParams.get("ref"));
+    if (!pack) {
+      sendJson(res, 404, { ok: false, error: "transaction_class_pack_not_found" });
+      return;
+    }
+    sendJson(res, 200, { ok: true, class_pack: pack });
+    return;
+  }
+
   if (req.method === "GET" && url.pathname === "/v1/transaction-center/default-loops") {
     sendJson(res, 200, buildDefaultTransactionGuidedLoopCatalog());
     return;
@@ -1121,6 +1312,36 @@ async function routeRequest(req, res) {
     return;
   }
 
+  if (req.method === "POST" && url.pathname === "/v1/transaction-center/transaction-class-packs/run") {
+    const body = await readJsonBody(req);
+    const classPackRef = String(body && body.class_pack_ref || "").trim();
+    const pack = getTransactionClassPack(classPackRef);
+    if (!pack) {
+      sendJson(res, 404, { ok: false, error: "transaction_class_pack_not_found" });
+      return;
+    }
+    const payload = buildTransactionClassPackRunPayload(body);
+    if (!payload) {
+      sendJson(res, 404, { ok: false, error: "transaction_class_pack_not_found" });
+      return;
+    }
+    const result = executeCommandRequest(state, payload, req.headers);
+    if (result.status !== 200) {
+      sendJson(res, result.status, result.payload);
+      return;
+    }
+    sendJson(res, 200, {
+      ok: true,
+      class_pack: pack,
+      result: result.payload,
+      result_set_summary: summarizeResultSetPayload(buildResultSetFromCommandResult(result.payload)),
+      linked_record_summary: summarizeLinkedRecordSetPayload(buildLinkedRecordSetFromCommandResult(result.payload)),
+      activity_summary: summarizeActivitySnapshotPayload(buildActivitySnapshotFromCommandResult(result.payload)),
+      proof_handoff_summary: buildProofHandoffSummary(result.payload, classPackRef)
+    });
+    return;
+  }
+
   if (req.method === "POST" && url.pathname === "/x402/mcp/tools/invoke") {
     const body = await readJsonBody(req);
     const payload = buildMcpInvokePayload(body, { paymentProtocol: "x402" });