xytara 1.5.0 → 1.7.0

package/README.md

@@ -75,6 +75,36 @@ The package and service also expose a default transaction center surface so the
 
 That same default center is also reflected in direct helper paths for default MCP usage, so the default path can be previewed or quoted without repeating the full integration-selection story each time.
 
+The `1.6.0` convergence line starts broadening that same default path into grouped first-party entry packs:
+
+- `default.mcp.tool.invoke`
+- `default.a2c.tooling.run`
+- `default.identity.anchor.run`
+
+These default packs are intended to make the public machine loop easier to consume as grouped first-party paths instead of only as low-level primitives.
+
+The package and service now also expose:
+
+- default transaction economics visibility
+- default transaction task-pack catalog, summary, and detail routes
+- direct SDK helpers for default task-pack preview, quote, and invoke
+
+The next `1.6.0` carry also adds guided default loops on top of those packs:
+
+- default loop catalog and detail routes
+- direct loop-run service surface
+- SDK helpers that return bundled result-set, linked-record, activity, and economics summaries together
+
+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.5.0";
+const COMMERCE_SDK_VERSION = "1.7.0";
 const COMMERCE_API_VERSION = "v1";
 
 function createClient(options) {

package/lib/catalog_contract.js

@@ -2,6 +2,191 @@
 
 const { catalog, findTask, findWorkflow } = require("../fixtures/catalog");
 
+function buildDefaultTransactionTaskPacks() {
+  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;
+  const suggestedPaths = Array.isArray(center.suggested_paths) ? center.suggested_paths : [];
+  const defaultMcpPath = suggestedPaths.find((entry) => entry && entry.path_id === "default_mcp_x402_path") || null;
+  const defaultA2cPath = suggestedPaths.find((entry) => entry && entry.path_id === "default_a2c_tooling_flow") || null;
+  return [
+    {
+      pack_ref: "default.mcp.tool.invoke",
+      title: "Default MCP Tool Invoke",
+      description: "Run one MCP tool through the built-in default transaction path.",
+      pack_kind: "task_set",
+      usage_mode: "direct_invoke",
+      default_protocol: "mcp",
+      default_payment_protocol: defaultPaymentProtocol,
+      default_settlement_mode: defaultSettlementMode,
+      suggested_path_id: defaultMcpPath ? defaultMcpPath.path_id : null,
+      selection_reason: "first_party_default_task_pack",
+      task_refs: ["adapter.mcp.invoke"],
+      workflow_ref: null,
+      required_inputs: ["tool_name"],
+      optional_inputs: ["arguments", "settlement_mode", "payment_protocol"]
+    },
+    {
+      pack_ref: "default.a2c.tooling.run",
+      title: "Default A2C Tooling Run",
+      description: "Open an A2C session, preview a tooling pack, and invoke an MCP tool through the default path.",
+      pack_kind: "workflow_pack",
+      usage_mode: "guided_flow",
+      default_protocol: "mcp",
+      default_payment_protocol: defaultPaymentProtocol,
+      default_settlement_mode: defaultSettlementMode,
+      suggested_path_id: defaultA2cPath ? defaultA2cPath.path_id : null,
+      selection_reason: "first_party_default_workflow_pack",
+      task_refs: ["a2c.session.open", "a2c.pack.preview", "adapter.mcp.invoke"],
+      workflow_ref: "a2c.tooling.flow",
+      required_inputs: ["agent_id", "channel_ref", "pack_ref", "tool_name"],
+      optional_inputs: ["arguments", "settlement_mode", "payment_protocol"]
+    },
+    {
+      pack_ref: "default.identity.anchor.run",
+      title: "Default Identity Anchor Run",
+      description: "Preview identity attestation, register the record, link it, and anchor the resulting commitment.",
+      pack_kind: "workflow_pack",
+      usage_mode: "guided_flow",
+      default_protocol: null,
+      default_payment_protocol: defaultPaymentProtocol,
+      default_settlement_mode: defaultSettlementMode,
+      suggested_path_id: null,
+      selection_reason: "first_party_default_identity_pack",
+      task_refs: ["identity.attest.preview", "registry.register", "identity.registry.link", "anchoring.submit"],
+      workflow_ref: "identity.anchor.flow",
+      required_inputs: ["subject_id", "record_type", "registry_record_id", "commitment_hash"],
+      optional_inputs: ["registry_scope", "settlement_mode", "payment_protocol"]
+    }
+  ];
+}
+
+function buildDefaultTransactionGuidedLoops() {
+  const center = buildDefaultTransactionCenter();
+  const taskPacks = buildDefaultTransactionTaskPacks();
+  const economics = buildDefaultTransactionEconomics();
+  const buildLoop = (loopRef, packRef, title, description, stages) => {
+    const pack = taskPacks.find((entry) => entry && entry.pack_ref === packRef) || null;
+    return {
+      loop_ref: loopRef,
+      pack_ref: packRef,
+      title,
+      description,
+      stage_count: Array.isArray(stages) ? stages.length : 0,
+      stages: Array.isArray(stages) ? stages : [],
+      default_protocol: pack && pack.default_protocol ? pack.default_protocol : center.default_protocol.protocol,
+      default_payment_protocol: economics.payment_protocol,
+      default_settlement_mode: economics.default_settlement_mode,
+      suggested_path_id: pack && pack.suggested_path_id ? pack.suggested_path_id : null,
+      workflow_ref: pack && pack.workflow_ref ? pack.workflow_ref : null
+    };
+  };
+  return [
+    buildLoop(
+      "default.mcp.loop",
+      "default.mcp.tool.invoke",
+      "Default MCP Loop",
+      "Preview, quote, pay, invoke, and inspect one MCP tool through the built-in first-party path.",
+      ["preview", "quote", "pay", "invoke", "inspect"]
+    ),
+    buildLoop(
+      "default.a2c.tooling.loop",
+      "default.a2c.tooling.run",
+      "Default A2C Tooling Loop",
+      "Open a session, preview a pack, invoke a tool, and inspect the resulting linked records.",
+      ["preview", "quote", "pay", "session", "invoke", "inspect"]
+    ),
+    buildLoop(
+      "default.identity.anchor.loop",
+      "default.identity.anchor.run",
+      "Default Identity Anchor Loop",
+      "Preview identity attestation, register, link, anchor, and inspect the resulting default transaction records.",
+      ["preview", "quote", "pay", "register", "anchor", "inspect"]
+    )
+  ];
+}
+
+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;
@@ -85,6 +270,161 @@ function summarizeDefaultTransactionCenter() {
   };
 }
 
+function buildDefaultTransactionEconomics() {
+  const center = buildDefaultTransactionCenter();
+  const settlement = center.default_settlement || {};
+  const payment = center.default_payment || {};
+  const treasury = center.default_treasury || {};
+  return {
+    ok: true,
+    brand: center.brand,
+    product: "default transaction economics",
+    payment_protocol: payment.protocol || null,
+    payment_scheme: payment.payment_scheme || center.payment_scheme || null,
+    default_settlement_mode: settlement.settlement_mode || null,
+    supported_settlement_modes: Array.isArray(settlement.supported_modes) ? settlement.supported_modes : [],
+    settlement_adapter: settlement.adapter || null,
+    settlement_asset: settlement.asset || null,
+    payee_agent_id: settlement.payee_agent_id || null,
+    payee_label: settlement.payee_label || null,
+    treasury_destination_kind: treasury.destination_kind || null,
+    treasury_destination_template: treasury.destination_template || null,
+    suggested_path_ids: Array.isArray(center.suggested_paths)
+      ? center.suggested_paths.map((entry) => entry && entry.path_id).filter(Boolean)
+      : []
+  };
+}
+
+function summarizeDefaultTransactionEconomics() {
+  const economics = buildDefaultTransactionEconomics();
+  return {
+    ok: true,
+    brand: economics.brand,
+    product: economics.product,
+    payment_protocol: economics.payment_protocol,
+    payment_scheme: economics.payment_scheme,
+    default_settlement_mode: economics.default_settlement_mode,
+    settlement_mode_count: economics.supported_settlement_modes.length,
+    supported_settlement_modes: economics.supported_settlement_modes,
+    treasury_destination_kind: economics.treasury_destination_kind,
+    payee_agent_id: economics.payee_agent_id,
+    suggested_path_count: economics.suggested_path_ids.length,
+    suggested_path_ids: economics.suggested_path_ids
+  };
+}
+
+function buildDefaultTransactionTaskPackCatalog() {
+  const center = buildDefaultTransactionCenter();
+  const packs = buildDefaultTransactionTaskPacks();
+  return {
+    ok: true,
+    brand: center.brand,
+    product: "default transaction task packs",
+    default_protocol: center.default_protocol && center.default_protocol.protocol ? center.default_protocol.protocol : null,
+    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,
+    pack_count: packs.length,
+    packs
+  };
+}
+
+function summarizeDefaultTransactionTaskPacks() {
+  const catalogResponse = buildDefaultTransactionTaskPackCatalog();
+  const packs = Array.isArray(catalogResponse.packs) ? catalogResponse.packs : [];
+  return {
+    ok: true,
+    brand: catalogResponse.brand,
+    product: catalogResponse.product,
+    default_protocol: catalogResponse.default_protocol,
+    default_payment_protocol: catalogResponse.default_payment_protocol,
+    default_settlement_mode: catalogResponse.default_settlement_mode,
+    pack_count: packs.length,
+    pack_refs: packs.map((entry) => entry && entry.pack_ref).filter(Boolean),
+    direct_pack_count: packs.filter((entry) => entry && entry.pack_kind === "task_set").length,
+    workflow_pack_count: packs.filter((entry) => entry && entry.pack_kind === "workflow_pack").length,
+    packs
+  };
+}
+
+function getDefaultTransactionTaskPack(ref) {
+  const normalized = String(ref || "").trim();
+  if (!normalized) return null;
+  return buildDefaultTransactionTaskPacks().find((entry) => entry && entry.pack_ref === normalized) || null;
+}
+
+function buildDefaultTransactionGuidedLoopCatalog() {
+  const center = buildDefaultTransactionCenter();
+  const loops = buildDefaultTransactionGuidedLoops();
+  return {
+    ok: true,
+    brand: center.brand,
+    product: "default transaction guided loops",
+    default_protocol: center.default_protocol && center.default_protocol.protocol ? center.default_protocol.protocol : null,
+    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,
+    loop_count: loops.length,
+    loops
+  };
+}
+
+function summarizeDefaultTransactionGuidedLoops() {
+  const catalogResponse = buildDefaultTransactionGuidedLoopCatalog();
+  const loops = Array.isArray(catalogResponse.loops) ? catalogResponse.loops : [];
+  return {
+    ok: true,
+    brand: catalogResponse.brand,
+    product: catalogResponse.product,
+    default_protocol: catalogResponse.default_protocol,
+    default_payment_protocol: catalogResponse.default_payment_protocol,
+    default_settlement_mode: catalogResponse.default_settlement_mode,
+    loop_count: loops.length,
+    loop_refs: loops.map((entry) => entry && entry.loop_ref).filter(Boolean),
+    loops
+  };
+}
+
+function getDefaultTransactionGuidedLoop(ref) {
+  const normalized = String(ref || "").trim();
+  if (!normalized) return null;
+  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,
@@ -216,11 +556,22 @@ function getWorkflowDetail(ref) {
 
 module.exports = {
   buildCatalogResponse,
+  buildDefaultTransactionEconomics,
   buildDefaultTransactionCenter,
+  buildDefaultTransactionGuidedLoopCatalog,
+  buildDefaultTransactionTaskPackCatalog,
+  buildTransactionClassPackCatalog,
   getCatalog,
+  getDefaultTransactionGuidedLoop,
+  getDefaultTransactionTaskPack,
+  getTransactionClassPack,
   getTaskDetail,
   getWorkflowDetail,
   getWorkflowList,
   summarizeCatalog,
-  summarizeDefaultTransactionCenter
+  summarizeDefaultTransactionCenter,
+  summarizeDefaultTransactionEconomics,
+  summarizeDefaultTransactionGuidedLoops,
+  summarizeDefaultTransactionTaskPacks,
+  summarizeTransactionClassPacks
 };