xytara 1.0.0

package/index.js

@@ -0,0 +1,25 @@
+"use strict";
+
+const { CommerceClient } = require("./lib/commerce_client");
+const {
+  ADAPTER_INTERFACE_VERSION,
+  validateAdapterImplementation
+} = require("./adapters/interfaces");
+
+const COMMERCE_SDK_NAME = "xytara";
+const COMMERCE_SDK_VERSION = "1.0.0";
+const COMMERCE_API_VERSION = "v1";
+
+function createClient(options) {
+  return new CommerceClient(options);
+}
+
+module.exports = {
+  COMMERCE_SDK_NAME,
+  COMMERCE_SDK_VERSION,
+  COMMERCE_API_VERSION,
+  ADAPTER_INTERFACE_VERSION,
+  CommerceClient,
+  createClient,
+  validateAdapterImplementation
+};

package/lib/catalog_contract.js

@@ -0,0 +1,141 @@
+"use strict";
+
+const { catalog, findTask, findWorkflow } = require("../fixtures/catalog");
+
+function buildCatalogResponse() {
+  return {
+    ok: true,
+    brand: "xytara",
+    product: "governed transaction rail",
+    version: catalog.version,
+    catalog_version: catalog.version,
+    currency: catalog.currency,
+    payment_scheme: catalog.payment_scheme,
+    plans: catalog.plans,
+    capabilities: catalog.capabilities,
+    adapters: catalog.adapters,
+    settlement_profiles: catalog.settlement_profiles,
+    task_categories: catalog.task_categories,
+    workflows: catalog.workflows,
+    surfaces: catalog.surfaces,
+    tasks: catalog.tasks
+  };
+}
+
+function summarizeCatalog() {
+  const fullCatalog = buildCatalogResponse();
+  return {
+    ok: true,
+    brand: fullCatalog.brand,
+    product: fullCatalog.product,
+    version: fullCatalog.catalog_version,
+    currency: fullCatalog.currency,
+    payment_scheme: fullCatalog.payment_scheme,
+    capabilities: fullCatalog.capabilities,
+    adapters: fullCatalog.adapters,
+    task_count: fullCatalog.tasks.length,
+    workflow_count: fullCatalog.workflows.length,
+    category_count: fullCatalog.task_categories.length,
+    task_categories: fullCatalog.task_categories,
+    settlement_profile_count: fullCatalog.settlement_profiles.length,
+    settlement_profiles: fullCatalog.settlement_profiles,
+    workflows: fullCatalog.workflows,
+    tasks: fullCatalog.tasks.map((task) => ({
+      task_ref: task.public_task_ref,
+      internal_task_ref: task.task_ref,
+      public_task_ref: task.public_task_ref,
+      aliases: task.public_aliases,
+      category: task.public_category,
+      title: task.public_title,
+      execution_mode: task.execution_mode,
+      pricing_band: task.pricing_band,
+      public_launch_price: task.public_launch_price,
+      pricing_note: task.pricing_note,
+      latency_class: task.latency_class,
+      failure_posture: task.failure_posture,
+      capabilities: task.capabilities,
+      adapters: task.adapters
+    })),
+    workflow_summaries: fullCatalog.workflows.map((workflow) => ({
+      workflow_ref: workflow.workflow_ref,
+      aliases: workflow.aliases,
+      category: workflow.category,
+      title: workflow.title,
+      task_count: workflow.task_count,
+      latency_class: workflow.latency_class,
+      failure_posture: workflow.failure_posture,
+      pricing_basis: workflow.pricing_basis
+    }))
+  };
+}
+
+function getCatalog() {
+  return buildCatalogResponse();
+}
+
+function getTaskDetail(ref) {
+  const task = findTask(ref);
+  if (!task) {
+    return null;
+  }
+  return {
+    task_ref: task.task_ref,
+    public_task_ref: task.public_task_ref,
+    aliases: task.public_aliases,
+    category: task.public_category,
+    title: task.public_title,
+    execution_mode: task.execution_mode,
+    pricing_band: task.pricing_band,
+    public_launch_price: task.public_launch_price,
+    pricing_note: task.pricing_note,
+    latency_class: task.latency_class,
+    failure_posture: task.failure_posture,
+    input_schema: task.input_schema,
+    capabilities: task.capabilities,
+    adapters: task.adapters
+  };
+}
+
+function buildWorkflowShape(workflow) {
+  const workflowTasks = (Array.isArray(workflow.task_refs) ? workflow.task_refs : [])
+    .map((taskRef) => findTask(taskRef))
+    .filter(Boolean)
+    .map((task) => ({
+      public_task_ref: task.public_task_ref,
+      task_ref: task.task_ref,
+      title: task.public_title,
+      category: task.public_category,
+      latency_class: task.latency_class,
+      failure_posture: task.failure_posture,
+      pricing_band: task.pricing_band,
+      public_launch_price: task.public_launch_price
+    }));
+  return {
+    ...workflow,
+    pricing_note: "Workflow pricing is determined by the quoted task set, not a fixed bundle price.",
+    task_refs: workflowTasks.map((task) => task.public_task_ref || task.task_ref),
+    task_count: workflowTasks.length,
+    tasks: workflowTasks
+  };
+}
+
+function getWorkflowList() {
+  return catalog.workflows.map(buildWorkflowShape);
+}
+
+function getWorkflowDetail(ref) {
+  const workflow = findWorkflow(ref);
+  if (!workflow) {
+    return null;
+  }
+  return buildWorkflowShape(workflow);
+}
+
+module.exports = {
+  buildCatalogResponse,
+  getCatalog,
+  getTaskDetail,
+  getWorkflowDetail,
+  getWorkflowList,
+  summarizeCatalog
+};

package/lib/catalog_views.js

@@ -0,0 +1,36 @@
+"use strict";
+
+const { buildMissingResponse } = require("./resource_views");
+
+function buildTaskDetailResponse(task) {
+  if (!task) {
+    return buildMissingResponse("task_not_found");
+  }
+  return {
+    status: 200,
+    payload: { ok: true, task }
+  };
+}
+
+function buildWorkflowListResponse(workflows) {
+  return {
+    status: 200,
+    payload: { ok: true, workflows }
+  };
+}
+
+function buildWorkflowDetailResponse(workflow) {
+  if (!workflow) {
+    return buildMissingResponse("workflow_not_found");
+  }
+  return {
+    status: 200,
+    payload: { ok: true, workflow }
+  };
+}
+
+module.exports = {
+  buildTaskDetailResponse,
+  buildWorkflowDetailResponse,
+  buildWorkflowListResponse
+};

package/lib/command_flow.js

@@ -0,0 +1,42 @@
+"use strict";
+
+const {
+  createCommandResult,
+  createQuote,
+  hydrateQuoteStates
+} = require("./commerce_runtime");
+
+function executeCommandRequest(state, payload, headers) {
+  hydrateQuoteStates(state);
+  if (!headers["x-wallet-id"] || !headers["x-payment"] || !headers["x-payment-signature"]) {
+    const quote = createQuote(state, payload);
+    return {
+      status: 402,
+      payload: { ok: false, quote }
+    };
+  }
+
+  const quote = payload.quote_id && state.quotes.get(payload.quote_id)
+    ? state.quotes.get(payload.quote_id)
+    : createQuote(state, payload);
+
+  if (quote && quote.status === "expired") {
+    return {
+      status: 409,
+      payload: {
+        ok: false,
+        reason: "quote_expired",
+        quote
+      }
+    };
+  }
+
+  return {
+    status: 200,
+    payload: createCommandResult(state, payload, quote)
+  };
+}
+
+module.exports = {
+  executeCommandRequest
+};

package/lib/commerce_artifacts.js

@@ -0,0 +1,294 @@
+"use strict";
+
+const crypto = require("crypto");
+const { findTask } = require("../fixtures/catalog");
+
+function classifyObservedLatency(durationMs) {
+  if (durationMs <= 1000) return "instant";
+  if (durationMs <= 15000) return "near_real_time";
+  return "governed_async";
+}
+
+function assessLatency(declaredLatencyClass, observedLatencyClass) {
+  const order = {
+    instant: 1,
+    near_real_time: 2,
+    governed_async: 3
+  };
+  const declared = order[declaredLatencyClass] || 99;
+  const observed = order[observedLatencyClass] || 99;
+  return observed <= declared ? "within_posture" : "outside_posture";
+}
+
+function createCommandArtifacts(payload, quote, options) {
+  const opts = options || {};
+  const transactionId = `txn_${crypto.randomBytes(6).toString("hex")}`;
+  const receiptId = `rcpt_${crypto.randomBytes(6).toString("hex")}`;
+  const startedAt = new Date();
+  const durationMs = 250;
+  const completedAt = new Date(startedAt.getTime() + durationMs);
+  const requestedTasks = Array.isArray(payload.tasks) && payload.tasks.length > 0
+    ? payload.tasks.map((task, index) => ({
+        task_id: task && task.task_id ? String(task.task_id).trim() : `task_${index + 1}`,
+        task_ref: task && task.task_ref ? String(task.task_ref).trim() : ""
+      }))
+    : [{
+        task_id: "task_1",
+        task_ref: String(payload.task_ref || "").trim()
+      }];
+  const resolvedTasks = requestedTasks
+    .map((task) => {
+      const catalogTask = findTask(task.task_ref);
+      return catalogTask ? { ...task, catalogTask } : null;
+    })
+    .filter(Boolean);
+  const primaryTask = resolvedTasks[0] && resolvedTasks[0].catalogTask ? resolvedTasks[0].catalogTask : null;
+  const declaredLatencyClass = (primaryTask && primaryTask.latency_class) || "near_real_time";
+  const observedLatencyClass = classifyObservedLatency(durationMs);
+  const deferredCompletion = opts.deferredCompletion === true;
+  const timing = {
+    declared_latency_class: declaredLatencyClass,
+    started_at_iso: startedAt.toISOString(),
+    completed_at_iso: deferredCompletion ? null : completedAt.toISOString(),
+    duration_ms: deferredCompletion ? null : durationMs,
+    observed_latency_class: deferredCompletion ? null : observedLatencyClass,
+    assessment: deferredCompletion ? "pending" : assessLatency(declaredLatencyClass, observedLatencyClass)
+  };
+  const resultTasks = resolvedTasks.length > 0 ? resolvedTasks : requestedTasks.map((task) => ({
+    ...task,
+    catalogTask: null
+  }));
+  const normalizedBody = payload && payload.body && typeof payload.body === "object" && !Array.isArray(payload.body)
+    ? payload.body
+    : {};
+  const resultsByTaskId = Object.fromEntries(resultTasks.map((task, index) => [
+    task.task_id,
+    (() => {
+      const base = {
+        task_ref: task.task_ref,
+        status: "completed",
+        output_ref: `output_${transactionId}_${index + 1}`
+      };
+      if (task.task_ref === "admission.preview") {
+        base.preview_kind = "admission";
+        base.admission_ref = `admission_${transactionId}_${index + 1}`;
+      }
+      if (task.task_ref === "trust.handoff.emit") {
+        base.handoff_kind = "trust";
+        base.handoff_action = "emit";
+        base.handoff_ref = `trust_handoff_${transactionId}_${index + 1}`;
+      }
+      if (task.task_ref === "trust.handoff.validate") {
+        base.handoff_kind = "trust";
+        base.handoff_action = "validate";
+        base.handoff_ref = `trust_handoff_${transactionId}_${index + 1}`;
+      }
+      if (task.task_ref === "execution_receipt.handoff.emit") {
+        base.handoff_kind = "execution_receipt";
+        base.handoff_action = "emit";
+        base.handoff_ref = `execution_receipt_handoff_${transactionId}_${index + 1}`;
+      }
+      if (task.task_ref === "execution_receipt.handoff.validate") {
+        base.handoff_kind = "execution_receipt";
+        base.handoff_action = "validate";
+        base.handoff_ref = `execution_receipt_handoff_${transactionId}_${index + 1}`;
+      }
+      if (task.task_ref === "receipt_ledger.handoff.emit") {
+        base.handoff_kind = "receipt_ledger";
+        base.handoff_action = "emit";
+        base.handoff_ref = `receipt_ledger_handoff_${transactionId}_${index + 1}`;
+      }
+      if (task.task_ref === "receipt_ledger.handoff.validate") {
+        base.handoff_kind = "receipt_ledger";
+        base.handoff_action = "validate";
+        base.handoff_ref = `receipt_ledger_handoff_${transactionId}_${index + 1}`;
+      }
+      if (task.task_ref === "runtime.emit") {
+        base.runtime_ref = `runtime_event_${transactionId}_${index + 1}`;
+        base.runtime_action = "emit";
+      }
+      if (task.task_ref === "runtime.anchor") {
+        base.anchor_ref = `anchor_${transactionId}_${index + 1}`;
+        base.runtime_action = "anchor";
+      }
+      if (task.task_ref === "runtime.emit_anchor") {
+        base.runtime_ref = `runtime_event_${transactionId}_${index + 1}`;
+        base.anchor_ref = `anchor_${transactionId}_${index + 1}`;
+        base.runtime_action = "emit_anchor";
+      }
+      if (task.task_ref === "registry.register") {
+        base.registry_record_ref = `registry_${transactionId}_${index + 1}`;
+      }
+      if (task.task_ref === "anchoring.submit") {
+        base.anchor_ref = `anchor_${transactionId}_${index + 1}`;
+      }
+      if (task.task_ref === "adapter.mcp.invoke") {
+        base.adapter_lane = "mcp";
+        base.tool_name = normalizedBody.tool_name || null;
+        base.invocation_status = "simulated";
+      }
+      return base;
+    })()
+  ]));
+  const capabilityScopes = Array.from(new Set(resultTasks.flatMap((task) =>
+    Array.isArray(task.catalogTask && task.catalogTask.capabilities) ? task.catalogTask.capabilities : []
+  )));
+  const adaptersUsed = Array.from(new Set(resultTasks.flatMap((task) =>
+    Array.isArray(task.catalogTask && task.catalogTask.adapters) ? task.catalogTask.adapters : []
+  )));
+  const remediation = {
+    status: "none",
+    reason_code: null,
+    active_case_type: null,
+    active_case_id: null,
+    compensating_action_status: null,
+    updated_at_iso: completedAt.toISOString()
+  };
+  const transaction = {
+    transaction_id: transactionId,
+    account_id: quote.account_id,
+    status: deferredCompletion ? "accepted" : "completed",
+    intent: payload.command || "command.execute",
+    amount_minor: quote.amount_minor,
+    currency: quote.currency,
+    quote_id: quote.quote_id,
+    output_ref: `output_${transactionId}`,
+    callback_url: payload.callback_url || null,
+    capabilities: quote.capabilities,
+    adapters: quote.adapters,
+    execution: {
+      status: deferredCompletion ? "accepted" : "completed",
+      task_count: resultTasks.length,
+      capability_scopes: capabilityScopes,
+      adapters_used: adaptersUsed,
+      results_by_task_id: resultsByTaskId
+    },
+    created_at_iso: startedAt.toISOString(),
+    completed_at_iso: deferredCompletion ? null : completedAt.toISOString(),
+    timing,
+    remediation
+  };
+  const receipt = {
+    receipt_id: receiptId,
+    transaction_id: transactionId,
+    account_id: quote.account_id,
+    status: deferredCompletion ? "pending" : "completed",
+    amount_minor: quote.amount_minor,
+    currency: quote.currency,
+    quote_id: quote.quote_id,
+    proof_ref: `proof_${receiptId}`,
+    execution_summary: {
+      command: payload.command || "command.execute",
+      task_count: resultTasks.length,
+      tasks: resultTasks.map((task) => ({
+        task_id: task.task_id,
+        task_ref: task.task_ref
+      }))
+    },
+    created_at_iso: deferredCompletion ? startedAt.toISOString() : completedAt.toISOString(),
+    timing,
+    remediation
+  };
+  const command = {
+    command: payload.command || "command.execute",
+    deliverables: resultTasks.map((task, index) => ({
+      kind: task.task_ref === "admission.preview" ? "preview" : "result",
+      task_id: task.task_id,
+      task_ref: task.task_ref,
+      ref: `deliverable_${transactionId}_${index + 1}`,
+      ...(task.task_ref === "admission.preview"
+        ? {
+            admission_ref: `admission_${transactionId}_${index + 1}`
+          }
+        : {}),
+      ...(task.task_ref === "trust.handoff.emit"
+        ? {
+            handoff_kind: "trust",
+            handoff_action: "emit",
+            handoff_ref: `trust_handoff_${transactionId}_${index + 1}`
+          }
+        : {}),
+      ...(task.task_ref === "trust.handoff.validate"
+        ? {
+            handoff_kind: "trust",
+            handoff_action: "validate",
+            handoff_ref: `trust_handoff_${transactionId}_${index + 1}`
+          }
+        : {}),
+      ...(task.task_ref === "execution_receipt.handoff.emit"
+        ? {
+            handoff_kind: "execution_receipt",
+            handoff_action: "emit",
+            handoff_ref: `execution_receipt_handoff_${transactionId}_${index + 1}`
+          }
+        : {}),
+      ...(task.task_ref === "execution_receipt.handoff.validate"
+        ? {
+            handoff_kind: "execution_receipt",
+            handoff_action: "validate",
+            handoff_ref: `execution_receipt_handoff_${transactionId}_${index + 1}`
+          }
+        : {}),
+      ...(task.task_ref === "receipt_ledger.handoff.emit"
+        ? {
+            handoff_kind: "receipt_ledger",
+            handoff_action: "emit",
+            handoff_ref: `receipt_ledger_handoff_${transactionId}_${index + 1}`
+          }
+        : {}),
+      ...(task.task_ref === "receipt_ledger.handoff.validate"
+        ? {
+            handoff_kind: "receipt_ledger",
+            handoff_action: "validate",
+            handoff_ref: `receipt_ledger_handoff_${transactionId}_${index + 1}`
+          }
+        : {}),
+      ...(task.task_ref === "runtime.emit"
+        ? {
+            runtime_ref: `runtime_event_${transactionId}_${index + 1}`,
+            runtime_action: "emit"
+          }
+        : {}),
+      ...(task.task_ref === "runtime.anchor"
+        ? {
+            anchor_ref: `anchor_${transactionId}_${index + 1}`,
+            runtime_action: "anchor"
+          }
+        : {}),
+      ...(task.task_ref === "runtime.emit_anchor"
+        ? {
+            runtime_ref: `runtime_event_${transactionId}_${index + 1}`,
+            anchor_ref: `anchor_${transactionId}_${index + 1}`,
+            runtime_action: "emit_anchor"
+          }
+        : {}),
+      ...(task.task_ref === "registry.register"
+        ? {
+            registry_record_ref: `registry_${transactionId}_${index + 1}`
+          }
+        : {}),
+      ...(task.task_ref === "anchoring.submit"
+        ? {
+            anchor_ref: `anchor_${transactionId}_${index + 1}`
+          }
+        : {}),
+      ...(task.task_ref === "adapter.mcp.invoke"
+        ? {
+            adapter_lane: "mcp",
+            tool_name: normalizedBody.tool_name || null
+          }
+        : {})
+    })),
+    monitor: {
+      transaction_id: transactionId,
+      status_url: `/v1/governed-transactions/${transactionId}`,
+      receipt_url: `/v1/receipts/${receiptId}`,
+      delivery_url: `/v1/deliveries/delivery_${transactionId}`
+    }
+  };
+  return { transaction, receipt, command };
+}
+
+module.exports = {
+  createCommandArtifacts
+};