@agenzo/merchant-cli 0.9.5 → 0.10.0

package/dist/index.js

@@ -910,6 +910,42 @@ function memberIdOf(opts) {
   return trimmed.length > 0 ? trimmed : void 0;
 }
 
+// src/price-annotation.ts
+var ORIGINAL_DESCRIPTION = "Original (pre-discount) price in integer cents. Optional, RECORD-ONLY: stored on our own order / charge record and echoed back in the order detail, never sent to the acquiring gateway and never used to derive or validate the amount charged (that always comes from the order's locked authoritative price).";
+var DISCOUNT_DESCRIPTION = "Discount amount in integer cents. Optional, RECORD-ONLY: same semantics as --original-amount-cents.";
+var PRICE_ANNOTATION_FLAGS = {
+  "original-amount-cents": {
+    type: "int",
+    required: false,
+    description: ORIGINAL_DESCRIPTION,
+    constraints: "non-negative integer cents"
+  },
+  "discount-amount-cents": {
+    type: "int",
+    required: false,
+    description: DISCOUNT_DESCRIPTION,
+    constraints: "non-negative integer cents"
+  }
+};
+function applyPriceAnnotation(body, opts) {
+  const mappings = [
+    ["--original-amount-cents", "originalAmountCents", "original_amount_cents"],
+    ["--discount-amount-cents", "discountAmountCents", "discount_amount_cents"]
+  ];
+  for (const [flag, optKey, bodyKey] of mappings) {
+    const raw = opts[optKey];
+    if (raw === void 0) continue;
+    const cents = Number(raw);
+    if (!Number.isInteger(cents) || cents < 0) {
+      throw new CliError(
+        "PARAM_INVALID",
+        `Invalid ${flag} "${raw}". Expected a non-negative integer number of cents (e.g. 10000 for 100.00).`
+      );
+    }
+    body[bodyKey] = cents;
+  }
+}
+
 // src/ride-elife/watch.ts
 var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
   "At destination",
@@ -1250,7 +1286,8 @@ var ridePayOrderSchema = {
       type: "string",
       required: true,
       description: "Unique key (1-128 chars [A-Za-z0-9_-]) forwarded verbatim as the Idempotency-Key header; never auto-generated"
-    }
+    },
+    ...PRICE_ANNOTATION_FLAGS
   },
   response: {
     order_id: { type: "string", description: "Authoritative order_ref (rio_\u2026, = order document _id) that was settled" },
@@ -1851,6 +1888,7 @@ var hotelPayOrderSchema = {
       description: "Unique key forwarded verbatim as the Idempotency-Key header; never auto-generated. Derive from business intent (e.g. hash(order_id + attempt)) and reuse the SAME key when retrying the same payment",
       constraints: "1-128 chars [A-Za-z0-9_-]"
     },
+    ...PRICE_ANNOTATION_FLAGS,
     watch: { type: "bool", required: false, default: false, description: "Poll automatically on PAYMENT_NOT_COMPLETED until PAID or timeout. Each iteration emits one NDJSON line" },
     "watch-interval": { type: "int", required: false, default: 5, description: "Seconds between poll attempts in --watch mode" },
     "watch-timeout": { type: "int", required: false, default: 300, description: "Total seconds before giving up in --watch mode" }
@@ -2679,7 +2717,8 @@ var flightPayOrderSchema = flightSchema(
     "return-url": { type: "string", required: false, description: "Optional 3DS/passkey return URL for the network-token authenticate path; falls back to the platform EVO_3DS_RETURN_URL." },
     "authorized-charge-no": { type: "string", required: false, description: "Resume a network-token 3DS challenge: charge_no from a prior AUTHENTICATION_REQUIRED response (settled via resume_token), then triggers ticketing on success." },
     "evo-explicit": { type: "bool", required: false, default: false, description: "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call order via the EVO bound-card fallback rail. Set true ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side." },
-    "idempotency-key": { type: "string", required: true, description: "Forwarded verbatim as the Idempotency-Key header." }
+    "idempotency-key": { type: "string", required: true, description: "Forwarded verbatim as the Idempotency-Key header." },
+    ...PRICE_ANNOTATION_FLAGS
   },
   { order_no: { type: "string", description: "Our order reference." }, status: { type: "string", description: "PAID on success; AUTHENTICATION_REQUIRED when the card needs 3DS." } },
   { command: "agenzo-merchant-cli flight-flink pay-order --order-no ffo_... --idempotency-key k2", output_summary: "Order becomes PAID; poll get-order until TICKETED." }
@@ -2788,7 +2827,8 @@ var flightChangePaySchema = flightSchema(
     "payment-method-id": { type: "string", required: false, description: "Optional bound-card id (EVO path)." },
     "payment-token-id": { type: "string", required: false, description: "Optional UPI network-token id (unionpay charge path)." },
     "authorized-merchant-trans-id": { type: "string", required: false, description: "Resume a 3DS challenge with the merchant trans id of the already-authorised preauth; the platform reuses and captures it instead of authorizing again." },
-    "idempotency-key": { type: "string", required: true, description: "Idempotency-Key header." }
+    "idempotency-key": { type: "string", required: true, description: "Idempotency-Key header." },
+    ...PRICE_ANNOTATION_FLAGS
   },
   {
     change_order_no: { type: "string", description: "Change order number." },
@@ -2833,6 +2873,66 @@ var flightRefundConfirmSchema = flightSchema(
   { status: { type: "int", description: "Refund status after the action." } },
   { command: "agenzo-merchant-cli flight-flink refund-confirm --refund-order-no R1 --confirm 1 --idempotency-key k7", output_summary: "Refund confirmed or cancelled." }
 );
+var DATA_NOUN = "data-aisa";
+function dataSchema(spec) {
+  return { cli: CLI_NAME, noun: DATA_NOUN, ...spec };
+}
+var dataListCategoriesSchema = dataSchema({
+  verb: "list-categories",
+  description: "List the data categories and how many capabilities each one holds. Free: answered from the bundled index, no upstream call.",
+  flags: {
+    // No flags of its own — authentication rides on the global --api-key.
+  },
+  response: {
+    categories: { type: "array", description: "Categories ordered by size; each item is {category, endpoints}." }
+  },
+  example: { command: "agenzo-merchant-cli data-aisa list-categories", output_summary: 'The data categories with a capability count each \u2014 use it to answer "what can you look up".' }
+});
+var dataSearchSchema = dataSchema({
+  verb: "search",
+  description: "Find a data capability by keyword. Free: answered from the bundled index, no upstream call. Returns operationId + method + path + tags + summary + price_usd for each hit.",
+  flags: {
+    keyword: { type: "string", required: false, constraints: "Space- or comma-separated tokens, matched against operationId / path / summary / tags. Omitted returns the first `limit` capabilities as examples.", description: "What to look for, e.g. 'crypto price' or 'reddit'." },
+    limit: { type: "int", required: false, default: 15, constraints: "1..50; defaults to 15.", description: "How many hits to return." }
+  },
+  response: {
+    results: { type: "array", description: "Matching capabilities; each item is {operationId, method, path, tags, summary, price_usd}. Relay operationId VERBATIM into describe / query." }
+  },
+  example: { command: "agenzo-merchant-cli data-aisa search --keyword 'crypto price' --limit 5", output_summary: "Hits with operationId + price_usd; describe the chosen one before running it." }
+});
+var dataDescribeSchema = dataSchema({
+  verb: "describe",
+  description: "Read one capability's parameter spec, usage hint and unit price before calling it. Free: answered from the bundled index, no upstream call.",
+  flags: {
+    "operation-id": { type: "string", required: true, constraints: "An operationId returned by search, verbatim.", description: "Which capability to describe." }
+  },
+  response: {
+    operationId: { type: "string", description: "The capability id \u2014 pass it unchanged to query." },
+    method: { type: "string", description: "Upstream HTTP method of the capability." },
+    path: { type: "string", description: "Upstream path of the capability." },
+    params: { type: "array", description: "Declared parameters; each item is {name, in, required, type, desc}. `desc` may be an empty string." },
+    required: { type: "array", description: "Names of the required parameters." },
+    usage: { type: "string", description: "Human-readable call guidance: which params are required, where each one sits, how to assemble --params." },
+    price_usd: { type: "number|null", description: "Unit price of one query call, in USD." },
+    tags: { type: "array", description: "Categories this capability belongs to." },
+    cost_tier: { type: "string|null", description: "Coarse price band of this capability." }
+  },
+  example: { command: "agenzo-merchant-cli data-aisa describe --operation-id get_coingecko_simple_price", output_summary: "Parameter spec + unit price; build --params from params[].name, then query." }
+});
+var dataQuerySchema = dataSchema({
+  verb: "query",
+  description: "Run one capability and return its data. Charged per call. READ-ONLY: it fetches data and nothing else.",
+  flags: {
+    "operation-id": { type: "string", required: true, constraints: "An operationId returned by search, verbatim.", description: "Which capability to run." },
+    params: { type: "object", required: false, constraints: "A JSON object keyed by the parameter names from describe. Passed through as a whole; unknown keys are dropped.", description: "The capability's parameters." },
+    "idempotency-key": { type: "string", required: false, constraints: "Optional. [A-Za-z0-9_-]{1,128}. When absent the request is still sent (no prompt, nothing generated) and de-duplication falls back to the result cache.", description: "Caller-supplied de-duplication key, forwarded verbatim as the Idempotency-Key header." }
+  },
+  response: {
+    data: { type: "object", description: "The capability response, verbatim." },
+    cost_usd: { type: "number", description: "What this call cost, in USD." }
+  },
+  example: { command: `agenzo-merchant-cli data-aisa query --operation-id get_coingecko_simple_price --params '{"ids":"bitcoin","vs_currencies":"usd"}'`, output_summary: "Returns data (upstream payload, verbatim) plus cost_usd for this call." }
+});
 
 // src/ride-elife/quote.ts
 function need(value, flag) {
@@ -3384,6 +3484,12 @@ function registerRidePayOrderCommand(parent, deps) {
   ).option(
     "--idempotency-key <key>",
     "Idempotency key forwarded verbatim as the Idempotency-Key header"
+  ).option(
+    "--original-amount-cents <cents>",
+    PRICE_ANNOTATION_FLAGS["original-amount-cents"].description
+  ).option(
+    "--discount-amount-cents <cents>",
+    PRICE_ANNOTATION_FLAGS["discount-amount-cents"].description
   );
   attachSchemaHelp(cmd, ridePayOrderSchema);
   cmd.action(async () => {
@@ -3411,6 +3517,7 @@ function registerRidePayOrderCommand(parent, deps) {
     if (opts.returnUrl !== void 0) body.return_url = opts.returnUrl;
     if (authorizedChargeNo !== void 0) body.authorized_charge_no = authorizedChargeNo;
     if (opts.evoExplicit) body.evo_explicit = true;
+    applyPriceAnnotation(body, opts);
     if (!isYes) {
       const confirmed = await confirm3({
         message: `Settle ride order ${orderId}? This charges the card and creates the ride (AWAITING_PAYMENT \u2192 PAID).`,
@@ -5408,7 +5515,7 @@ function registerHotelPayOrderCommand(parent, deps) {
   ).option(
     "--idempotency-key <key>",
     "Idempotency key forwarded verbatim as the Idempotency-Key header"
-  ).option("--watch", "Poll until PAID or timeout (NDJSON output)", false).option(
+  ).option("--original-amount-cents <cents>", PRICE_ANNOTATION_FLAGS["original-amount-cents"].description).option("--discount-amount-cents <cents>", PRICE_ANNOTATION_FLAGS["discount-amount-cents"].description).option("--watch", "Poll until PAID or timeout (NDJSON output)", false).option(
     "--watch-interval <seconds>",
     "Seconds between polls when --watch is set",
     String(DEFAULT_PAY_WATCH_INTERVAL_SECONDS)
@@ -5449,6 +5556,7 @@ function registerHotelPayOrderCommand(parent, deps) {
       body.authorized_charge_no = opts.authorizedChargeNo;
     }
     if (opts.evoExplicit) body.evo_explicit = true;
+    applyPriceAnnotation(body, opts);
     if (!isYes) {
       const confirmed = await confirm8({
         message: `Settle hotel order ${orderId}? This moves money via the order's configured billing mode (monthly_settlement or pay_per_call).`,
@@ -6865,7 +6973,13 @@ function registerPayOrderCommand(parent, deps) {
   ).option(
     "--evo-explicit",
     "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call order via the EVO bound-card fallback rail. Set ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side."
-  ).option("--idempotency-key <key>", "Forwarded verbatim as the Idempotency-Key header");
+  ).option("--idempotency-key <key>", "Forwarded verbatim as the Idempotency-Key header").option(
+    "--original-amount-cents <cents>",
+    PRICE_ANNOTATION_FLAGS["original-amount-cents"].description
+  ).option(
+    "--discount-amount-cents <cents>",
+    PRICE_ANNOTATION_FLAGS["discount-amount-cents"].description
+  );
   attachSchemaHelp(cmd, flightPayOrderSchema);
   cmd.action(async () => {
     const opts = cmd.optsWithGlobals();
@@ -6897,6 +7011,7 @@ function registerPayOrderCommand(parent, deps) {
       body.authorized_charge_no = opts.authorizedChargeNo;
     }
     if (opts.evoExplicit) body.evo_explicit = true;
+    applyPriceAnnotation(body, opts);
     const result = await deps.apiClient.post(
       `/flight/${encodeURIComponent(orderNo)}/pay`,
       { type: "api-key", key: apiKey },
@@ -7175,7 +7290,13 @@ function registerChangePayCommand(parent, deps) {
   const cmd = parent.command("change-pay").description("Pay a change request fee (like a normal order) and trigger change ticketing").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--change-order-no <id>", "Change order number").option("--order-no <id>", "Original order reference (ownership check)").option("--amount <amount>", "Change fee total in decimal units (change-detail price_total)").option("--currency <currency>", "ISO 4217 currency code", "USD").option("--payment-method-id <id>", "Optional bound-card id (EVO path)").option("--payment-token-id <id>", "Optional UPI network-token id (unionpay charge path)").option(
     "--authorized-merchant-trans-id <id>",
     "Resume a 3DS challenge: merchant trans id of the already-authorised preauth"
-  ).option("--idempotency-key <key>", "Forwarded verbatim as the Idempotency-Key header");
+  ).option("--idempotency-key <key>", "Forwarded verbatim as the Idempotency-Key header").option(
+    "--original-amount-cents <cents>",
+    PRICE_ANNOTATION_FLAGS["original-amount-cents"].description
+  ).option(
+    "--discount-amount-cents <cents>",
+    PRICE_ANNOTATION_FLAGS["discount-amount-cents"].description
+  );
   attachSchemaHelp(cmd, flightChangePaySchema);
   cmd.action(async () => {
     const opts = cmd.optsWithGlobals();
@@ -7196,6 +7317,7 @@ function registerChangePayCommand(parent, deps) {
     if (opts.authorizedMerchantTransId !== void 0) {
       body.authorized_merchant_trans_id = opts.authorizedMerchantTransId;
     }
+    applyPriceAnnotation(body, opts);
     if (!isYes) {
       const isResume = opts.authorizedMerchantTransId !== void 0;
       const message = isResume ? `Resume change fee ${amount} ${currency} for change order ${changeOrderNo}? The card is already authorised; this captures it and triggers change ticketing.` : `Pay change fee ${amount} ${currency} for change order ${changeOrderNo}? This charges the customer and triggers change ticketing.`;
@@ -7441,6 +7563,169 @@ function registerFlightSkillCommand(parent) {
   });
 }
 
+// src/data-aisa/_helpers.ts
+function need23(value, flag) {
+  if (value === void 0) {
+    throw new CliError("PARAM_INVALID", `Missing required --${flag}.`);
+  }
+  return value;
+}
+function num11(value, flag) {
+  const n = Number(need23(value, flag));
+  if (!Number.isFinite(n)) {
+    throw new CliError("PARAM_INVALID", `--${flag} must be a number.`);
+  }
+  return n;
+}
+function jsonObject(raw, flag) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CliError("PARAM_INVALID", `--${flag} must be a JSON object.`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new CliError("PARAM_INVALID", `--${flag} must be a JSON object.`);
+  }
+  return parsed;
+}
+function verbatimIdempotencyKey(raw, flag) {
+  if (!IDEMPOTENCY_KEY_PATTERN.test(raw)) {
+    throw new CliError(
+      "PARAM_INVALID",
+      `Invalid --${flag}: "${raw}". ${IDEMPOTENCY_KEY_RULE}`
+    );
+  }
+  return raw;
+}
+function resolveApiKey2(flag) {
+  return PromptEngine.resolveInput(flag, { message: "API Key:", type: "password" });
+}
+async function render4(data, format, text) {
+  const resolved = resolveFormat(format);
+  const result = { data, text: () => text(data) };
+  await renderWithContext(result, { format: resolved }, new ConfigManager());
+}
+function kv(data) {
+  const lines = Object.entries(data).map(([k, v]) => [
+    k,
+    typeof v === "object" && v !== null ? JSON.stringify(v) : String(v ?? "-")
+  ]);
+  return Formatter.keyValue(lines);
+}
+
+// src/data-aisa/list-categories.ts
+function registerDataListCategoriesCommand(parent, deps) {
+  const cmd = parent.command("list-categories").description(
+    "List the data categories and how many capabilities each one holds. Free (answered from the bundled index, no upstream call), read-only."
+  ).option("--api-key <key>", "API Key for authentication (X-Api-Key)");
+  attachSchemaHelp(cmd, dataListCategoriesSchema);
+  cmd.action(async () => {
+    const opts = cmd.optsWithGlobals();
+    const format = resolveFormat(opts.format);
+    const apiKey = await resolveApiKey2(opts.apiKey);
+    const spinner = format === "json" ? null : createSpinner("Fetching data categories...");
+    const result = await deps.apiClient.get("/data/categories", {
+      type: "api-key",
+      key: apiKey
+    });
+    spinner?.stop();
+    if (!result.success) throw CliError.fromApi(result, { auth: "api-key" });
+    await render4(result.data, opts.format, (d) => JSON.stringify(d, null, 2));
+  });
+}
+
+// src/data-aisa/search.ts
+function registerDataSearchCommand(parent, deps) {
+  const cmd = parent.command("search").description(
+    "Find a data capability by keyword. Free (answered from the bundled index, no upstream call), read-only. Returns operationId + method + path + tags + summary + price_usd for each hit."
+  ).option("--api-key <key>", "API Key for authentication (X-Api-Key)").option(
+    "--keyword <kw>",
+    "What to look for, e.g. 'crypto price' or 'reddit'. Space- or comma-separated tokens; omitted returns the first --limit capabilities as examples."
+  ).option("--limit <n>", "How many hits to return (1-50)", "15");
+  attachSchemaHelp(cmd, dataSearchSchema);
+  cmd.action(async () => {
+    const opts = cmd.optsWithGlobals();
+    const format = resolveFormat(opts.format);
+    const apiKey = await resolveApiKey2(opts.apiKey);
+    const params = {};
+    if (opts.keyword !== void 0) params.keyword = String(opts.keyword);
+    if (opts.limit !== void 0) {
+      params.limit = String(num11(opts.limit, "limit"));
+    }
+    const spinner = format === "json" ? null : createSpinner("Searching data capabilities...");
+    const result = await deps.apiClient.get(
+      "/data/search",
+      { type: "api-key", key: apiKey },
+      params
+    );
+    spinner?.stop();
+    if (!result.success) throw CliError.fromApi(result, { auth: "api-key" });
+    await render4(result.data, opts.format, (d) => JSON.stringify(d, null, 2));
+  });
+}
+
+// src/data-aisa/describe.ts
+function registerDataDescribeCommand(parent, deps) {
+  const cmd = parent.command("describe").description(
+    "Read one capability's parameter spec, usage hint and unit price before calling it. Free (answered from the bundled index, no upstream call), read-only."
+  ).option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--operation-id <id>", "Which capability to describe \u2014 an operationId returned by search, verbatim");
+  attachSchemaHelp(cmd, dataDescribeSchema);
+  cmd.action(async () => {
+    const opts = cmd.optsWithGlobals();
+    const format = resolveFormat(opts.format);
+    const operationId = need23(opts.operationId, "operation-id");
+    const apiKey = await resolveApiKey2(opts.apiKey);
+    const spinner = format === "json" ? null : createSpinner("Fetching capability spec...");
+    const result = await deps.apiClient.get(
+      `/data/describe/${encodeURIComponent(operationId)}`,
+      { type: "api-key", key: apiKey }
+    );
+    spinner?.stop();
+    if (!result.success) throw CliError.fromApi(result, { auth: "api-key" });
+    await render4(result.data, opts.format, (d) => kv(d));
+  });
+}
+
+// src/data-aisa/query.ts
+function registerDataQueryCommand(parent, deps) {
+  const cmd = parent.command("query").description(
+    "Run one capability and return its data. Charged per call. READ-ONLY: it fetches data and nothing else."
+  ).option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--operation-id <id>", "Which capability to run \u2014 an operationId returned by search, verbatim").option(
+    "--params <json>",
+    "The capability's parameters as a JSON object keyed by the parameter names from describe. Passed through as a whole; unknown keys are dropped."
+  ).option(
+    "--idempotency-key <key>",
+    "Optional de-duplication key (1-128 chars [A-Za-z0-9_-]) forwarded verbatim as the Idempotency-Key header; never auto-generated, and omitting it is fine"
+  );
+  attachSchemaHelp(cmd, dataQuerySchema);
+  cmd.action(async () => {
+    const opts = cmd.optsWithGlobals();
+    const format = resolveFormat(opts.format);
+    const operationId = need23(opts.operationId, "operation-id");
+    const body = { operation_id: operationId };
+    if (opts.params !== void 0) {
+      body.params = jsonObject(opts.params, "params");
+    }
+    let idempotencyKey;
+    if (opts.idempotencyKey !== void 0) {
+      idempotencyKey = verbatimIdempotencyKey(opts.idempotencyKey, "idempotency-key");
+    }
+    const extraHeaders = idempotencyKey ? { "Idempotency-Key": idempotencyKey } : void 0;
+    const apiKey = await resolveApiKey2(opts.apiKey);
+    const spinner = format === "json" ? null : createSpinner("Fetching data...");
+    const result = await deps.apiClient.post(
+      "/data/query",
+      { type: "api-key", key: apiKey },
+      body,
+      extraHeaders
+    );
+    spinner?.stop();
+    if (!result.success) throw CliError.fromApi(result, { auth: "api-key" });
+    await render4(result.data, opts.format, (d) => kv(d));
+  });
+}
+
 // src/index.ts
 var programRef;
 async function main() {
@@ -7611,6 +7896,13 @@ Key notes:
   registerRefundDetailCommand(flightCmd, deps);
   registerRefundConfirmCommand(flightCmd, deps);
   registerFlightSkillCommand(flightCmd);
+  const dataCmd = program.command("data-aisa").description(
+    "AIsa read-only information lookup (crypto, markets, web & news, SEO, social, prediction markets, research): list-categories / search / describe / query. Pay-per-call READ-ONLY lookups \u2014 it never places an order and never takes money."
+  );
+  registerDataListCategoriesCommand(dataCmd, deps);
+  registerDataSearchCommand(dataCmd, deps);
+  registerDataDescribeCommand(dataCmd, deps);
+  registerDataQueryCommand(dataCmd, deps);
   await program.parseAsync(process.argv);
 }
 function resolveActiveFormat() {