xytara 2.0.0 → 2.2.0

package/bin/xytara-run.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+"use strict";
+
+const crypto = require("crypto");
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+      continue;
+    }
+    args[key] = next;
+    index += 1;
+  }
+  return args;
+}
+
+function printUsage() {
+  process.stdout.write([
+    "Usage: xytara-run --url <service_url> --account <account_id> --command <intent> --task <task_ref> [options]",
+    "",
+    "Options:",
+    "  --body-json <json>        JSON body for the task payload",
+    "  --wallet-id <id>          Wallet id for local_signed x402 payment",
+    "  --wallet-secret <secret>  Shared secret for local_signed payment",
+    "  --txid <txid>             Existing BSV txid for bsv_teranode settlement",
+    "  --raw-tx <hex>            Raw BSV transaction for arc submission flows",
+    "  --quote-only              Stop after returning the payment challenge",
+    "  --pretty                  Pretty-print JSON output",
+    "  --help                    Show this help message"
+  ].join("\n"));
+}
+
+function parseJson(value, label) {
+  if (value == null || value === "") return {};
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new Error(`${label}_must_be_valid_json`);
+  }
+}
+
+async function postJson(url, payload, headers = {}) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...headers
+    },
+    body: JSON.stringify(payload)
+  });
+  const text = await response.text();
+  let json = null;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch (_) {
+    json = null;
+  }
+  return {
+    status: response.status,
+    ok: response.ok,
+    json,
+    text
+  };
+}
+
+function buildLocalSignedPaymentSignature({ quote, accountId, walletId, walletSecret, txid, rawTx }) {
+  const payment = {
+    account_id: accountId,
+    wallet_id: walletId,
+    quote_id: quote.quote_id,
+    amount_minor: quote.amount_minor,
+    currency: quote.currency,
+    settlement_mode: quote.settlement.mode,
+    settlement_binding_hash: quote.settlement_binding_hash
+  };
+
+  if (quote.settlement && quote.settlement.mode === "bsv_teranode") {
+    payment.bsv_teranode = {
+      network: quote.settlement.hints && quote.settlement.hints.network ? quote.settlement.hints.network : null,
+      merchant_address: quote.settlement.hints && quote.settlement.hints.merchant_address ? quote.settlement.hints.merchant_address : null,
+      amount_satoshis: quote.settlement.hints && quote.settlement.hints.amount_satoshis != null ? quote.settlement.hints.amount_satoshis : null,
+      settlement_reference: quote.settlement.hints && quote.settlement.hints.settlement_reference ? quote.settlement.hints.settlement_reference : null
+    };
+    if (txid) payment.bsv_teranode.txid = txid;
+    if (rawTx) payment.bsv_teranode.raw_tx = rawTx;
+  }
+
+  payment.issued_at_iso = new Date().toISOString();
+  payment.nonce = `xytara-cli-${Date.now()}`;
+
+  const encoded = Buffer.from(JSON.stringify(payment), "utf8").toString("base64url");
+  const signature = crypto.createHmac("sha256", walletSecret).update(encoded).digest("hex");
+  return Buffer.from(JSON.stringify({
+    scheme: "exact",
+    wallet_id: walletId,
+    payload: encoded,
+    signature
+  }), "utf8").toString("base64url");
+}
+
+function writeOutput(payload, pretty) {
+  process.stdout.write(JSON.stringify(payload, null, pretty ? 2 : 0));
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printUsage();
+    return;
+  }
+
+  const serviceUrl = String(args.url || "").replace(/\/$/, "");
+  const accountId = String(args.account || "").trim();
+  const command = String(args.command || "").trim();
+  const taskRef = String(args.task || args["task-ref"] || "").trim();
+  const body = parseJson(args["body-json"], "body_json");
+  const walletId = String(args["wallet-id"] || "").trim();
+  const walletSecret = String(args["wallet-secret"] || "").trim();
+  const txid = String(args.txid || "").trim() || null;
+  const rawTx = String(args["raw-tx"] || "").trim() || null;
+  const pretty = args.pretty === true;
+
+  if (!serviceUrl || !accountId || !command || !taskRef) {
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  const executeUrl = `${serviceUrl}/x402/commands/execute`;
+  const payload = {
+    account_id: accountId,
+    command,
+    task_ref: taskRef,
+    body
+  };
+
+  const challengeResult = await postJson(executeUrl, payload);
+  if (challengeResult.ok) {
+    writeOutput(challengeResult.json || { ok: true }, pretty);
+    return;
+  }
+  if (challengeResult.status !== 402 || !challengeResult.json || !challengeResult.json.payment_required) {
+    writeOutput(challengeResult.json || { ok: false, status: challengeResult.status, body: challengeResult.text || null }, pretty);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (args["quote-only"] === true || !walletId || !walletSecret) {
+    writeOutput(challengeResult.json, pretty);
+    return;
+  }
+
+  const quote = challengeResult.json.payment_required.quote;
+  const paymentSignature = buildLocalSignedPaymentSignature({
+    quote,
+    accountId,
+    walletId,
+    walletSecret,
+    txid,
+    rawTx
+  });
+  const paidPayload = {
+    ...payload,
+    quote_id: quote.quote_id
+  };
+  const paidResult = await postJson(executeUrl, paidPayload, {
+    "payment-signature": paymentSignature
+  });
+  if (!paidResult.ok) {
+    writeOutput(paidResult.json || { ok: false, status: paidResult.status, body: paidResult.text || null }, pretty);
+    process.exitCode = 1;
+    return;
+  }
+  writeOutput(paidResult.json || { ok: true }, pretty);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+});

package/examples/adapter_review_walkthrough.js

@@ -0,0 +1,53 @@
+"use strict";
+
+const assert = require("assert");
+const { createServer } = require("../server");
+
+async function fetchJson(url) {
+  const response = await fetch(url);
+  assert.strictEqual(response.ok, true, `request failed: ${url}`);
+  return response.json();
+}
+
+async function postJson(url, body) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json"
+    },
+    body: JSON.stringify(body)
+  });
+  assert.strictEqual(response.ok, true, `request failed: ${url}`);
+  return response.json();
+}
+
+async function main() {
+  const server = createServer();
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address();
+  const baseUrl = `http://127.0.0.1:${port}`;
+
+  try {
+    const partnerSummary = await fetchJson(`${baseUrl}/v1/adapter-partners/summary`);
+    assert.strictEqual(typeof partnerSummary.category, "string", "adapter partner summary missing");
+
+    const readiness = await fetchJson(`${baseUrl}/v1/integrations/promotion-readiness`);
+    assert.strictEqual(readiness.ok, true, "promotion readiness summary missing");
+
+    const actionPreview = await postJson(`${baseUrl}/v1/integrations/promotion-actions/preview`, {
+      integration_id: "partner.protocol.acme_mcp",
+      action: "complete_certification"
+    });
+    assert.strictEqual(actionPreview.ok, true, "promotion action preview missing");
+    assert.strictEqual(actionPreview.valid_now, true, "promotion action preview should be valid");
+
+    console.log("xytara adapter review walkthrough passed");
+  } finally {
+    await new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/examples/export_carried_handoff.js

@@ -0,0 +1,80 @@
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const path = require("path");
+const { createServer } = require("../server");
+const { createClient } = require("../index.js");
+
+function parseOutputPath(argv) {
+  const args = Array.isArray(argv) ? argv : [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--output" && args[index + 1]) {
+      return path.resolve(process.cwd(), args[index + 1]);
+    }
+  }
+  return path.resolve(process.cwd(), "examples", "generated.carried-handoff.json");
+}
+
+async function main() {
+  const outputPath = parseOutputPath(process.argv.slice(2));
+  const server = createServer();
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  const baseUrl = `http://127.0.0.1:${address.port}`;
+
+  try {
+    const client = createClient({
+      baseUrl,
+      apiKey: "demo-api-key",
+      walletId: "demo-wallet",
+      walletSecret: "demo-wallet-secret",
+      accountId: "acct_demo"
+    });
+
+    const health = await client.getHealthSummary();
+    assert.strictEqual(health.status, "ok", "health summary missing");
+
+    const exported = await client.exportInteractionResultPackage("result.spine.job.commitment", {
+      job_type: "batch.render",
+      job_id: "job-carried-handoff-demo",
+      source_zone_id: "zone.alpha",
+      target_zone_id: "zone.beta",
+      interaction_class: "cross_zone_job"
+    }, {
+      command: "carried-handoff-demo-export"
+    });
+
+    assert.strictEqual(
+      exported.portable_handoff_bundle.result_package_ref,
+      "result.spine.job.commitment",
+      "portable handoff result package ref missing"
+    );
+
+    const reviewInput = {
+      handoff_bundle: exported.portable_handoff_bundle
+    };
+
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, JSON.stringify(reviewInput, null, 2));
+
+    process.stdout.write(JSON.stringify({
+      ok: true,
+      output_file: outputPath,
+      result_package_ref: exported.portable_handoff_bundle.result_package_ref,
+      committed_ref: exported.portable_handoff_bundle.committed_ref,
+      proof_review_summary_surface: "/v1/proof-center/result-package-handoff/review/summary",
+      proof_run_surface: "/v1/proof-center/result-package-handoff/run",
+      next_xoonya_cli: `xoonya-review --file "${outputPath}" --summary`
+    }, null, 2));
+  } finally {
+    await new Promise((resolve, reject) => {
+      server.close((error) => (error ? reject(error) : resolve()));
+    });
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.stack || error.message}\n`);
+  process.exitCode = 1;
+});

package/examples/funded_runtime_walkthrough.js

@@ -0,0 +1,70 @@
+"use strict";
+
+const assert = require("assert");
+const { createServer } = require("../server");
+
+async function fetchJson(url, options) {
+  const response = await fetch(url, options);
+  assert.strictEqual(response.ok, true, `request failed: ${url}`);
+  return response.json();
+}
+
+async function postJson(url, body, headers = {}) {
+  return fetchJson(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: "Bearer demo-api-key",
+      ...headers
+    },
+    body: JSON.stringify(body)
+  });
+}
+
+async function main() {
+  const server = createServer();
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address();
+  const baseUrl = `http://127.0.0.1:${port}`;
+
+  try {
+    const packSummary = await fetchJson(`${baseUrl}/v1/credit-packs/summary`);
+    assert.strictEqual(packSummary.ok, true, "credit pack summary missing");
+    assert.strictEqual(packSummary.credit_pack_count > 0, true, "credit pack count missing");
+
+    const grant = await postJson(
+      `${baseUrl}/v1/credit-bridge/grants`,
+      {
+        account_id: "acct_demo",
+        pack_id: "credits.agent",
+        grant_units: 120,
+        settlement_ref: "settlement-funded-runtime-demo-1",
+        external_ref: "external-funded-runtime-demo-1"
+      },
+      {
+        authorization: "Bearer demo-credit-bridge-token"
+      }
+    );
+    assert.strictEqual(grant.ok, true, "credit bridge grant missing");
+
+    const balance = await fetchJson(`${baseUrl}/v1/economics/accounts/acct_demo/credit-balance`);
+    assert.strictEqual(balance.account_id, "acct_demo", "credit balance missing");
+    assert.strictEqual(balance.available_units > 0, true, "credit balance not funded");
+
+    const preview = await postJson(`${baseUrl}/v1/economics/rails/credits/preview-spend`, {
+      account_id: "acct_demo",
+      task_ref: "trust.verify",
+      units: 40
+    });
+    assert.strictEqual(preview.ok, true, "credit preview missing");
+
+    console.log("xytara funded runtime walkthrough passed");
+  } finally {
+    await new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/examples/partner_launch_walkthrough.js

@@ -0,0 +1,43 @@
+"use strict";
+
+const assert = require("assert");
+const { createServer } = require("../server");
+
+async function fetchJson(url, options) {
+  const response = await fetch(url, options);
+  assert.strictEqual(response.ok, true, `request failed: ${url}`);
+  return response.json();
+}
+
+async function main() {
+  const server = createServer();
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  const baseUrl = `http://127.0.0.1:${address.port}`;
+
+  try {
+    const releaseCenterSummary = await fetchJson(`${baseUrl}/v1/release-center/summary`);
+    assert.strictEqual(typeof releaseCenterSummary.category, "string", "release-center summary category missing");
+
+    const releaseCandidateSummary = await fetchJson(`${baseUrl}/v1/release-candidate/summary`);
+    assert.strictEqual(typeof releaseCandidateSummary.category, "string", "release-candidate summary category missing");
+
+    const durability = await fetchJson(`${baseUrl}/v1/runtime/durability`);
+    assert.strictEqual(durability.ok, true, "durability surface missing");
+    assert.strictEqual(typeof durability.operator_guidance, "string", "durability guidance missing");
+
+    const adapterPartnersSummary = await fetchJson(`${baseUrl}/v1/adapter-partners/summary`);
+    assert.strictEqual(typeof adapterPartnersSummary.category, "string", "adapter partners summary category missing");
+
+    console.log("xytara partner launch walkthrough passed");
+  } finally {
+    await new Promise((resolve, reject) => {
+      server.close((error) => (error ? reject(error) : resolve()));
+    });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});